Documentation

Get from install to a useful session

Prompt Gun is a minimalist terminal coding agent. The command you run is prompt-gun. The default surface is four tools — read, write, edit, bash — plus personalization through extensions, skills, templates, themes, and context files. Sessions stay on your machine. The software is MIT licensed; the grant is on the license page.

Install

Requires Node.js 22.19.0 or newer.

curl -fsSL https://prompt-gun.com/install.sh | sh

npm install -g --ignore-scripts prompt-gun
bun install -g prompt-gun
pnpm add -g --ignore-scripts prompt-gun

Then start it in the project directory you want it to work on:

cd /path/to/project
prompt-gun

Authenticate

Use a subscription through /login, or export an API key before launch. There is no Prompt Gun-hosted model plan.

prompt-gun
/login

Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro, and GitHub Copilot.

export ANTHROPIC_API_KEY=sk-ant-...
prompt-gun

Other built-in providers include OpenAI, Google Gemini and Vertex, Azure, Amazon Bedrock, xAI, Groq, OpenRouter, local llama.cpp routers, and the rest of the catalog. Select with /model or --provider / --model.

First prompt

Once the TUI starts, type a request and press Enter. For a one-shot run:

prompt-gun -p "Summarize this repository and tell me how to run its checks."

Built-in tools

• read — read file contents
• write — create or overwrite files
• edit — patch files with find/replace
• bash — run shell commands (PowerShell on Windows)

That four-tool core is the default. Tighten the allowlist for a read-only pass, or add capabilities with skills and extensions instead of growing the built-in set.

Context files

Prompt Gun loads AGENTS.md (or CLAUDE.md) from the user agent directory, parent directories, and the current working directory. Use them for project instructions, conventions, and common commands. A directory can ship AGENTS.override.md to replace that level. Disable discovery with --no-context-files (or -nc).

Replace the default system prompt with a project or user-level SYSTEM.md. Append without replacing via APPEND_SYSTEM.md. A smaller, deliberate prompt is the first token-efficiency lever.

Personalization

Drop resources into the user agent directory or the project agent directory:

• Extensions — TypeScript modules that register tools, commands, shortcuts, events, and UI.
• Skills — on-demand capability packages invoked with /skill:name or loaded by the agent.
• Prompt templates — Markdown files expanded with /name.
• Themes — palettes that hot-reload while the TUI is open.

Skills stay out of the system prompt until they are needed, which keeps routine turns cheaper. /reload picks up file changes for keybindings, extensions, skills, prompts, themes, and context files.

Sessions and compaction

Interactive work is saved locally, grouped by working directory. Resume the last session with prompt-gun -c, pick one with -r, jump with /tree, branch with /fork / /clone, and export with /export.

Long sessions can fill a context window. Compaction summarizes older messages and keeps recent ones. It runs automatically near the limit, or manually with /compact (optionally with extra instructions). The full history remains in the session file.

Other modes

prompt-gun -p "what does this repo build?"
prompt-gun --mode json
prompt-gun --mode rpc

Print mode also reads piped stdin and merges it into the prompt. JSON mode emits events as lines. RPC mode is for process integration over stdin/stdout.

Uninstall

npm uninstall -g prompt-gun
bun uninstall -g prompt-gun
pnpm remove -g prompt-gun

Uninstalling the CLI leaves settings, credentials, sessions, and installed packages in the agent config directory.