plk

Command sequence merger CLI — detects repeated command patterns from your shell history and lets you save/run them as shortcuts.

The Problem

You keep typing the same multi-step command sequences:

cd ~/project/frontend
pnpm run dev

git add .
git commit -m "wip"
git push

Every time. Manually. plk detects these patterns automatically and lets you run them with a single command.

Installation

From source

git clone https://github.com/BeepBoopBit/plk.git
cd plk
cargo build --release
cp target/release/plk ~/.local/bin/

From crates.io

cargo install plk

Quick Start

# 1. Install the shell hook
plk init --shell zsh   # or bash

# 2. Reload your shell
source ~/.zshrc

# 3. Use your shell normally — plk records commands in the background

# 4. After repeating patterns, check what plk detected
plk ls auto

# 5. Run a detected sequence
plk auto <id>

# 6. Save it as a named shortcut
plk save <id> --name dev

# 7. Run it anytime
plk run dev

See QUICKSTART.md for a detailed walkthrough.

Commands

How It Works

1. A shell hook (installed via plk init) records every command you run with its timestamp and working directory
2. plk segments your history into sessions (split by 5s gaps)
3. Repeated sequences of 2+ commands are detected and ranked by frequency
4. When a sequence is repeated enough times (default 10), plk suggests saving it:

   plk: "cd ~/project/frontend && pnpm run dev" repeated 10x. Save it? Run: plk save a1b2c3 --name <name>
        To dismiss: plk dismiss a1b2c3
   

5. You can browse, run, or save these as named shortcuts

Configuration

Optional config at ~/.config/plk/config.toml:

# Time gap (ms) that splits history into sessions (default: 5000)
session_gap_ms = 5000

# Minimum repetitions to detect a sequence (default: 2)
min_frequency = 2

# Only consider history from the last N days (default: 30)
history_days = 30

# Maximum history entries to keep (default: 10000)
max_history_entries = 10000

# Suggest saving a sequence after this many repetitions (default: 10, 0 to disable)
suggestion_threshold = 10

# Enable swapx integration — plk will write rules to ~/.config/swapx/rules.plk.yaml (default: false)
swapx_integration = false

Data Storage

Override with PLK_DATA_DIR and PLK_CONFIG_DIR environment variables.

swapx Integration

If you use swapx, plk can automatically register rules so that typing the first command of a shortcut triggers a swapx prompt.

Setup

During plk init, if swapx is detected on your system, plk will ask:

swapx detected. Enable swapx integration? (y/N)

You can also enable it manually in ~/.config/plk/config.toml:

swapx_integration = true

How it works

When you save a shortcut, plk writes a rule to ~/.config/swapx/rules.plk.yaml (a separate file from your manual swapx rules). The rule uses the raw command you typed as the match — so if you use zoxide and type cd project, the swapx match is cd project, not the resolved absolute path.

plk will also ask whether the rule should be global or directory-scoped:

Swapx rule scope — directory (/home/user/projects) or global? (d/G)

• Global (default) — the rule triggers anywhere
• Directory — the rule only triggers when you're in that specific directory (uses swapx's dir field)

Example

plk add --name dev "cd prompt && pnpm run dev"
# Swapx rule scope — directory (/home/user/projects) or global? (d/G) G

Now typing cd prompt triggers swapx:

? cd prompt
  > plk: dev (cd prompt && pnpm run dev)
    just cd prompt (default)

Removing a shortcut (plk rm) or resetting (plk reset) cleans up rules.plk.yaml automatically — your manual swapx rules in rules.yaml are never touched.

Shell Support

• zsh — full support (hook + tab completions with descriptions)
• bash — full support (hook + tab completions)

Tip: Use zoxide for Smarter cd

zoxide is a smarter cd that learns which directories you visit most. It pairs well with plk — when you type cd project instead of cd /home/user/long/path/to/project, plk records the short alias you actually typed, making detected sequences more readable and swapx rules more intuitive.

Tip: Use fzf for Better Tab Completion

If you have fzf installed, its tab completion integration gives you a much nicer experience — fuzzy filtering, a preview of each sequence, and arrow-key selection instead of cycling through options.

For zsh, add to your .zshrc (after plk init):

# fzf must be set up first: https://github.com/junegunn/fzf#setting-up-shell-integration
source <(fzf --zsh)

For bash, add to your .bashrc (after plk init):

eval "$(fzf --bash)"

Then plk auto <TAB> will open an fzf picker with the sequence descriptions.

License

MIT