Pragma

Pragma is an open-source, terminal-based agentic coding assistant. It runs in your project directory, reads and edits your code, executes commands, and manages git — all driven by LLM tool use. It ships as a single binary with an interactive TUI and a scriptable headless mode.

Features

• Interactive TUI — Bubble Tea interface with a conversation timeline, tool-approval prompts, inspectors for plans/files/tools/git, a command palette, and mouse support.
• Headless mode — Run a single task from a script or another agent; output goes to stdout.
• Plan mode — The agent proposes a step-by-step plan with validation commands, scope, fallbacks, and per-step estimates before touching any code.
• Built-in tool system — File I/O, shell execution, git operations, web fetch, code graph queries, sub-agents, and an ask_user interaction tool. Each tool has a permission level (r--/rw-/rwx/---) with configurable approval.
• Output filters — Summarize, grep, head/tail, line-range, JSON pretty-print, dedup, and stats filters on tool output.
• Code graph — Tree-sitter parses your source into a symbol-and-edge graph stored in SQLite, with incremental reindexing by content hash.
• Budget-aware model tiering — Define multiple model tiers; Pragma automatically switches to cheaper models as spend approaches your budget limit.
• Session persistence — Conversations are stored in SQLite and can be resumed with --resume <uuid>.
• Context compaction — Automatically summarizes history when approaching the model's token limit.
• Process sandbox — Seccomp (Linux), sandbox profiles (macOS), and restricted open (Windows) block dangerous syscalls and executables.
• Multi-provider — Supports Anthropic and OpenAI protocols out of the box, with automatic OpenRouter fallback for unknown providers.

Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/AamindMandragora/pragma/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/AamindMandragora/pragma/main/install.ps1 | iex

The binary is installed to ~/.pragma/bin/. Add it to your PATH if the installer doesn't do so automatically.

Build from source

Requires Go 1.26+.

git clone https://github.com/AamindMandragora/pragma.git
cd pragma
go build -o pragma .

Quick start

# Launch the interactive TUI in your project directory
cd your-project
pragma

# Or run a single task in headless mode
pragma --headless "Fix the failing tests in pkg/auth"

# Pipe a prompt via stdin
echo "Summarize the current architecture" | pragma --headless

Configuration

Pragma reads its config from .agent/config.toml in your project root. API keys are loaded from .agent/.env, then .env, then environment variables.

# Model tiers — ordered from most to least expensive.
# Pragma starts with the first tier and switches down as spend
# crosses each threshold.
[[model.tiers]]
model           = "gpt-5.4-mini"
provider        = "openai"
api_key_var_name = "OPENAI_API_KEY"
temperature     = 0.7
max_tokens      = 16384
effort          = "high"
threshold       = 0          # use from the start

[[model.tiers]]
model           = "gpt-5.4-mini"
provider        = "openai"
api_key_var_name = "OPENAI_API_KEY"
temperature     = 0.5
max_tokens      = 8192
effort          = "low"
threshold       = 0.8        # switch after 80% of budget spent

[behavior]
verbosity        = "minimal"  # minimal | normal | verbose
test_policy      = "none"     # none | suggest | auto
max_output_tokens = 16384

[context]
max_input_tokens = 128000
dependency       = ""

CLI reference

pragma [prompt]             Launch TUI (default) or pass a prompt to start immediately
pragma headless [prompt]    Run one task without the TUI

Flags:
  --headless            Run in headless mode
  --config <path>       Path to a custom config file
  --budget <float>      Set the spending budget for this session
  --resume <uuid>       Resume a previous session
  --sessions            List past sessions
  --version             Print version and exit

TUI controls

Shortcut	Action
Alt+P	Toggle plan mode
Alt+Shift+P	Open plan inspector
Alt+F	Open files inspector
Alt+T	Open tools inspector
Alt+G	Open git inspector
Alt+K	Command palette
Alt+H / F1	Keyboard help
Esc	Stop active run / clear composer
Alt+C	Cancel and quit

Type #help in the composer for the full shortcut list and all hash commands.

Project structure

cmd/              CLI entry points (root, headless, TUI launcher)
internal/
  agent/          Agent loop, plan execution, context compaction
  tui/            Bubble Tea TUI (views, input, menus, onboarding)
  llm/            Provider abstraction (Anthropic, OpenAI), model catalog
  tools/          Tool interface, registry, permission system
    codegraph/    Tree-sitter code graph queries
    exec/         Shell and Python execution
    files/        Read, write, edit, move, delete
    filters/      Output post-processing (summarize, grep, etc.)
    git/          Branch, commit, diff, log, stash, status
    interaction/  ask_user tool
    subagent/     Delegated sub-agent tasks
    web/          Web fetch
  graph/          Tree-sitter indexer and edge resolution
  db/             SQLite connection and migrations
  process/        Process manager, sandboxing, .agentignore
  config/         TOML config loader
  app/            Runtime bootstrap
csrc/             C sandbox code (Linux seccomp, macOS, Windows)

Contributing

1. Fork the repo and create a feature branch.
2. Make your changes and ensure go build succeeds.
3. Open a pull request against main.

License

See the repository for license details.