Getting started with hocket

The drop-in orchestrator

The prevailing answer to "how do I run many agents at once" is remote: sandboxes, microVMs, a fleet of cloud checkouts. That buys hard isolation — and costs you boot time, image drift, credential syncing, and distance from the work.

hocket is the local alternative. Your machine already has everything an agent needs — your toolchains, your caches, your credentials, your dotfiles — and git already has an isolation unit built for parallel work:

• Worktrees are the sandbox. Every agent gets its own checkout on its own branch. Agents never collide on files; merging their work is a git operation, not a download.
• Spawning is a process spawn. A new worktree + agent is one keystroke and sub-second — there is no image to build, no VM to boot, no environment to reproduce.
• Everything is observable. Each agent is a live terminal you can read, scroll, and interrupt at any moment. A process pane shows what every worktree is actually running; a live git graph shows commits landing as agents make them.
• Attention comes to you. Agents roll up to working / needs-attention / unread / exited in the sidebar. When one needs you, you get a sound and a desktop notification; one key jumps you to it.

The honest boundary: worktrees isolate the work, not the process. Agents run with your permissions, like every other tool on your machine — that is the point, and it is the trust model you already use daily. For genuinely untrusted code, use a real sandbox; for the everyday loop with agents you already run by hand, hocket removes the ceremony.

Requirements

• macOS on Apple silicon (the alpha's one supported platform)
• git on your PATH
• Your agent CLIs (claude, codex, …) installed the way you already run them — hocket launches them, it doesn't bundle them
• A modern terminal. Ghostty, kitty, and iTerm2 speak the kitty keyboard protocol and unlock the cmd+… chords; every chord has an alt+… twin that works in any terminal

Install

1curl -fsSL https://get.hocket.dev/install.sh | bash

That downloads the latest release, verifies its SHA-256, and installs hocket into ~/.local/bin (override with HOCKET_INSTALL_DIR). Then:

1hocket --version

Prefer to see every step, or want a specific version? The manual path and checksums are in the README.

First launch

cd to wherever the work is and launch:

1cd ~/src && hocket      # a folder of repos: every project in the sidebar
2cd my-app && hocket     # a single repo: that project, ready for agents

The launch directory is the scan root — hocket drops into whatever you're looking at, no configuration required. To pin a fixed root instead of the launch directory, set one:

1HOCKET_ROOT=~/src hocket        # or set `root` in config.toml

You can also add projects from inside the app — click the projects header (or its +) and choose Find and add project… for a broot-style search starting at the scan root — browse upward from there, or reach any path via Find projects from path…. Adding and removing projects never touches your files or git data.

The loop

1. Spawn — alt+shift+n creates a fresh worktree off main and prompts for the agent to run — enter accepts your most recent agent command. Run it again for a second agent on a second worktree; they cannot step on each other.
2. Watch — the sidebar rolls status up live: a spinner while an agent works, ◆ when one needs you (with a sound and desktop banner), unread marks when a turn finished while you were elsewhere.
3. Act — alt+a jumps to the next agent that needs attention. Answer it, interrupt it, or open its worktree's files in the built-in editor right beside it. The git graph updates as commits land.
4. Merge and move on — worktree state is plain git; review, merge, and prune with your normal tools, or let auto-prune clean up merged worktrees.

Quit with ctrl+q — it confirms first if agents are still live. ctrl+c always belongs to the focused agent, never to hocket.

The keys that matter

The full keymap — and how to remap any of it — is docs/public/keymap.md.

Make it yours

~/.config/hocket/config.toml, all optional:

1root = "~/src"            # project scan root
2notifications = true      # sound + desktop banner when an agent needs you
3
4[keymap]
5"alt+j" = "session.next"  # chord → command overrides

Drop any audio file next to config.toml and it becomes the attention cue — no configuration needed. The full sound story (pools, muting, how cues reach you over ssh) is in the README.

Upgrade and uninstall

Upgrade by re-running the install one-liner — it always fetches the latest release, and your config and state carry over. Uninstall with hocket --uninstall — hocket cleans up after itself: it removes the binary and then asks whether to remove its config, state, and log too, so a full uninstall leaves nothing of hocket behind. Answer no (the default) to keep your data for a later reinstall, or clean up by hand: rm ~/.local/bin/hocket, then ~/.config/hocket/ and ~/.local/state/hocket/ for a clean slate. Nothing hocket removes ever touches your repositories, worktrees, or branches.

Learn more

• Keyboard map — every command and how to rebind it
• Window management — panes, tiling, the four saved Panels
• Glossary — the names for everything you see
• Architecture decisions — why it's built the way it is