packetcode

A keyboard-first, multi-provider AI coding agent for the terminal.

Status: pre-release / active development. This README describes the current main branch, not a tagged 1.0 release.

packetcode runs in your terminal, keeps your project in your hands, and can talk to OpenAI, Anthropic, Gemini, MiniMax, OpenRouter, and Ollama models through one interface. It can read, search, edit, patch, and run commands in the current project. File writes, patches, shell commands, background-agent writes, and MCP tool calls go through approval unless trust mode is enabled.

Start Here

Install the latest Linux/macOS release:

curl -fsSL https://raw.githubusercontent.com/packetloss404/packetcode/main/install.sh | bash

Set INSTALL_DIR=$HOME/.local/bin to install without sudo. The installer verifies the release checksum before installing and warns if the install directory is not on PATH.

curl -fsSL https://raw.githubusercontent.com/packetloss404/packetcode/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash

Build from source:

make build
./bin/packetcode

On Windows:

$commit = git rev-parse --short HEAD
go build -trimpath -ldflags "-s -w -X main.version=dev -X main.commit=$commit" -o bin/packetcode.exe ./cmd/packetcode
.\bin\packetcode.exe

First run starts a line-based setup flow: choose a provider, enter an API key if needed, pick a model, and save ~/.packetcode/config.toml. Ollama does not need a key, but it does need a reachable Ollama server.

Common launch flags:

packetcode --provider gemini --model gemini-2.5-pro
packetcode --resume <session-id>
packetcode --trust
packetcode --version

--provider and --model override the saved default for the current run. The provider must already be configured, except for Ollama.

Docs

• Getting started
• Providers and models
• Configuration
• Hooks and statusline
• MCP servers
• Agent View
• Packet Computers and Packet Control
• Troubleshooting

Core Workflow

Type a prompt and press Enter. Use Shift+Enter for a newline. If you submit while a foreground generation or /compact is still running, packetcode queues the prompt, shows it as You (queued), and runs it when the active operation finishes. During a generation, Ctrl+C cancels the current provider request, running tool, approval prompt, or queued foreground prompts; pressing Ctrl+C again while idle exits.

Destructive actions show an approval prompt:

• Y approves.
• N or Esc rejects.
• --trust or trust_mode = true auto-approves for the session.

Finalized messages are printed into your terminal scrollback. Use your terminal scroll, Shift+PageUp, or tmux copy mode to review older output. /transcript opens the current saved session transcript in the transcript viewer. /clear and Ctrl+L clear packetcode's live transcript pane; they do not delete the saved session.

The top bar shows foreground operation state such as thinking or compacting, elapsed time, queued prompt count, context usage, active background jobs, and provider/model information. Custom statusline commands receive the same operation data in their JSON snapshot.

Providers

Configured providers can be switched without restarting:

• Ctrl+P or /provider opens the provider picker.
• Ctrl+M or /model opens the model picker for the active provider.
• /provider <slug> switches directly.
• /model <id> switches directly.

To add or update a provider key, open the provider picker with Ctrl+P or /provider, focus the provider row, then press Ctrl+A. /provider add opens the same picker, and /provider add <slug> opens the same key prompt for a provider.

API keys can also be set in the environment:

PACKETCODE_OPENAI_API_KEY
PACKETCODE_ANTHROPIC_API_KEY
PACKETCODE_GEMINI_API_KEY
PACKETCODE_MINIMAX_API_KEY
PACKETCODE_OPENROUTER_API_KEY

Environment variables take precedence over ~/.packetcode/config.toml.

Background Agents

/spawn <prompt> starts a background agent. Background agents are read-only by default; use /spawn --write <prompt> when a delegated task may need file writes, patches, or shell commands. Write-capable background agents still go through the normal approval flow unless trust mode is enabled.

/agents opens Agent View, which groups jobs by state and shows provider/model, age, token counts, estimated cost, status badges, and recent activity. Enter or /agents <id> opens the transcript for a selected agent, p peeks, i injects a completed result, and c cancels.

See Agent View for the full workflow.

MCP Servers

MCP servers are configured under [mcp.<name>] and exposed as provider-safe <server>__<tool> aliases. packetcode starts each configured command as your user, so treat MCP servers as trusted local code; approval prompts gate tool calls, not the child process itself. MCP children inherit only a small launch environment allowlist by default, plus any per-server env values you configure. The /mcp command lists configured servers, /mcp status <name> shows health/config details, /mcp tools <name> lists provider-safe callable tool aliases, and /mcp logs <name> shows a bounded, redacted tail of the server stderr log.

Slash Commands

Built-in commands:

Command	Purpose
/spawn <prompt>	Start a read-only background agent.
/spawn --write <prompt>	Start a background agent that may request write/command approval.
/agents / /agents <id>	Open Agent View or a selected agent transcript.
/jobs / /jobs <id>	List jobs or open a job transcript.
/cancel <id|all>	Cancel one job or all jobs.
/provider [slug]	Open the provider picker or switch provider.
/provider add [slug]	Open the provider picker or key prompt.
/model [id]	Open the model picker or switch model.
/sessions	List recent sessions.
/sessions resume <id>	Resume by full ID or unique prefix.
/sessions delete <id> --yes	Delete a saved session.
/undo	Restore the most recent file snapshot.
/compact [--keep N]	Summarize older conversation messages.
/cost / /cost reset --yes	Show or reset cost totals.
/trust [on|off]	Show or set trust mode.
/help	Show keybindings and commands.
/clear	Clear the transcript pane only.
/transcript	Open the current saved session transcript.
/statusline [refresh]	Show or refresh a custom statusline.
/mcp / /mcp status <name> / /mcp tools <name> / /mcp logs <name>	Inspect configured MCP servers.
/exit / /quit	Quit packetcode.

Typing / opens command autocomplete. Unknown slash commands show an error; type //something to send /something as a normal prompt.

You can add markdown-backed prompt commands:

• User commands: ~/.packetcode/commands/<name>.md
• Project commands: .packetcode/commands/<name>.md

Project commands override user commands with the same name. Built-ins cannot be shadowed.

---
description: Review the selected code
---
Review this code and call out correctness risks:

$ARGUMENTS

/review internal/app sends the markdown body as the prompt with $ARGUMENTS replaced by internal/app.

Configuration

packetcode reads ~/.packetcode/config.toml and writes it with user-only permissions. A minimal config looks like:

[default]
provider = "openai"
model = "gpt-5.5"

[providers.openai]
api_key = "sk-..."
default_model = "gpt-5.5"

[providers.anthropic]
api_key = "sk-ant-..."
default_model = "claude-opus-4-7"

[providers.minimax]
api_key = "sk-..."
default_model = "MiniMax-M2.7-highspeed"

[providers.ollama]
host = "http://localhost:11434"
default_model = "qwen2.5-coder:14b"

[behavior]
trust_mode = false
auto_compact_threshold = 80
max_input_rows = 10
background_max_concurrent = 4
background_max_depth = 2
background_max_total = 32

See Configuration for the full schema.

Development

Requires Go 1.24.2+.

make verify
make test
make build
make smoke
make vulncheck
make goreleaser-check
golangci-lint run ./...

The repository also contains feature-design notes under docs/feature-*.md. User-facing behavior should be checked against the guides linked above and the current code.

Roadmap Notes

packetcode is pre-1.0. See BACKLOG.md for the current backlog and PACKETCOMPUTERS.md for the Packet Computers and Packet Control research plan.

License

MIT - see LICENSE.