puq code

puq code (puq) is a terminal-based AI coding agent. It reads your repository, runs commands, edits files, and answers questions about your code from an interactive terminal UI (TUI) or from scripts in headless mode.

With puq code you can:

  • Work interactively with an agent that can read, search, edit, and run code in your project
  • Run one-off prompts non-interactively for scripts and CI (puq -p "...")
  • Use any model in the puq catalog (Anthropic, OpenAI, Google, and more) with a single puq API key
  • Give the agent project knowledge through context files (AGENTS.md, RULES.md) and skills
  • Connect external tools through MCP (Model Context Protocol) servers
  • Resume, fork, export, and share sessions
  • Plan changes before editing, and split large tasks across subagents
  • Add your own slash commands, hooks, agents, and plugins
  • Answer /puq comments in GitHub issues and pull requests, or work inside ACP-compatible editors

Quick Start

# Install puq code (macOS / Linux)
curl -fsSL https://puq.sh/install.sh | sh

# Check that puq is installed
puq --version

# Log in with your puq API key
puq login puq

# Start an interactive session in your project
cd path/to/your/project
puq

# Or run a single prompt and exit
puq -p "Summarize the changes in the last commit"

Where puq code keeps its files

LocationPurpose
~/.puq/agent/config.ymlGlobal settings
~/.puq/agent/mcp.jsonUser-level MCP servers
~/.puq/agent/AGENTS.mdUser-level context file
~/.puq/agent/keybindings.ymlKeyboard shortcut remaps
~/.puq/agent/sessions/Saved sessions
<project>/.puq/Project-level settings, context files, skills, and MCP servers
<project>/.puq/agents/, commands/, skills/Project-level custom agents, slash commands, and skills

In this section