PocketBot

PocketBot (pb) is a tmux-backed launcher for Claude, Codex, opencode, and other long-running terminal workflows.

• A commandline app that keeps sessions alive in the background (using tmux)
• Lets you detach and reattach quickly (Ctrl+D to detach from a session)
• Supports multiple Claude/Codex/opencode instances per machine

Prerequisites:

• go (to build/install pb)
• tmux (required at runtime)
• fasder (optional, enables z directory jump)

go install github.com/zakandrewking/pocketbot/cmd/pb@latest

• c: attach Claude (create if none, picker if multiple)
• x: attach Codex (create if none, picker if multiple)
• o: attach opencode (create if none, picker if multiple)
• z: directory jump using fasder search + Enter
• n: create new instance (auto mode by default), then choose c, x, or o; optional f fresh / y yolo
• k: kill one instance, then choose c, x, or o (picker appears if needed)
• d: back or quit UI (sessions keep running)
• Esc: go back/cancel in picker-style flows
• Ctrl+C: kill all sessions and quit

pb

Typical loop:

1. Press c, x, or o to jump into a coding session.
2. Press Ctrl+D to detach back to pb.
3. Press n to spin up another instance for a parallel task.
4. Press k to clean up a specific instance.

Create ~/.config/pocketbot/config.yaml:

claude:
  command: "claude --continue --permission-mode acceptEdits"
  key: "c"
  enabled: true

codex:
  command: "codex resume --last"
  key: "x"
  enabled: true

opencode:
  command: "opencode --continue"
  key: "o"
  enabled: true

sessions:
  - name: "dev-server"
    command: "npm run dev"
    key: "v"
  - name: "logs"
    command: "tail -f logs/app.log"
    key: "l"

Reserved keys in the default UI: c, x, o, z, n, k, d, Esc.

See config.example.yaml for more examples.

Add a .pocketbot file at a repository root to override only the settings for that repository. Use a token returned by claude setup-token to select a Claude account. If you have a Codex access token, you can select the Codex account independently:

claude:
  oauth_token: "paste-token-from-claude-setup-token-here"

codex:
  access_token: "paste-codex-access-token-here"

Codex access tokens are currently limited to ChatGPT Business and Enterprise workspaces; there is no codex setup-token equivalent for personal accounts. A workspace admin must allow access-token creation, after which eligible users can create one from the ChatGPT Access Tokens page. A 404 or forbidden response usually means the workspace plan or permissions do not allow token creation. See the official access-token documentation.

Pocketbot passes claude.oauth_token to Claude as CLAUDE_CODE_OAUTH_TOKEN, and codex.access_token to Codex as CODEX_ACCESS_TOKEN. Each token is passed only to its corresponding tool, never to opencode or custom sessions. .pocketbot is a partial YAML override, so omitted values continue to come from ~/.config/pocketbot/config.yaml and then the built-in defaults. If a local sessions list is present, it replaces the user-level list.

CLAUDE_CODE_OAUTH_TOKEN does not bypass Claude Code's initial onboarding. Run Claude Code normally and complete onboarding at least once before relying on repository tokens. After onboarding is complete, Claude Code respects the token Pocketbot supplies for each repository.

The file contains a secret. Keep it out of Git and make it readable only by your user:

printf '\n.pocketbot\n' >> .gitignore
chmod 600 .pocketbot

Pocketbot refuses to load either token from a file with group or other permissions. It finds the nearest .pocketbot between the current directory and the Git repository root, and reloads the applicable configuration after a z directory jump. Existing Claude and Codex sessions keep the token they started with; create a new session to use a changed token.

go run cmd/pb/main.go
go test ./...
go install ./cmd/pb

Apache License 2.0