Docs

DistilCode is a coding agent that runs in your terminal. It reads files, edits code and runs commands for you while keeping the context it sends to your model small. New here? Start with How to use to install it and run distil in a project.

Agents

Primary agents and subagents.

Press Tab (or Shift+Tab) to cycle the primary agent. Primary agents delegate focused work to subagents through the task tool.

Primary agents

build: The default agent. Reads, edits and runs commands within the permissions you have configured.
plan: Read-only planning mode. Edits are blocked except for the plan file; switch back to build to carry the plan out.
orchestration: Turns a request into a short plan and delegates each step to a right-sized subagent instead of doing the work itself.

Subagents

explore: Read-only codebase exploration and localisation. Uses codebase memory when it is enabled.
smartbash: Runs shell work described as a natural-language intent and reports the result. Never edits files.
general: General-purpose subagent for self-contained, multi-step tasks, including parallel work.

Control Panel

Toggles that change how the agent works.

The Control Panel sits at the bottom of the right sidebar. Press ctrl+o to focus it. The agent cannot change these settings itself; only you can, from the panel.

Agent behaviour

Ponytail: Reuse existing code, the standard library and native features, then write the shortest diff that works. On by default for primary agents.
Caveman: Compresses every reply to the fewest tokens that keep code, commands, paths and errors exact. Off by default. When it is on, it replaces Ponytail’s reply-length rules.

Persistence and context

Codebase memory: Keeps feature-level repository knowledge that the main and explore agents reuse across sessions.
smartCompress: Lets Jev decide when to compact your context instead of compacting at a fixed point.
Extend cache: Keeps the provider prompt cache warm while you are idle or waiting on a tool call.

Keyboard shortcuts

Default keybindings.

The leader key is ctrl+x: press it, release, then press the next key.

Everyday

ctrl+p: Open the command list.
ctrl+o: Focus the Control Panel.
tab / shift+tab: Next or previous primary agent.
escape: Interrupt the current response.
shift+enter: Insert a newline in the prompt.
ctrl+c: Exit.

Leader combinations

ctrl+x n: New session.
ctrl+x l: List sessions.
ctrl+x m: List models.
ctrl+x c: Compact the session.
ctrl+x b: Toggle the sidebar.
ctrl+x t: Change theme.
ctrl+x e: Open the prompt in your external editor.

Slash commands

Type / in the prompt.

Sessions

/new: Start a new session (alias /clear).
/sessions: Resume an earlier session (aliases /resume, /continue).
/compact: Summarise the conversation so far to free up context.
/undo, /redo: Revert or restore the last message and its file changes.

Setup

/connect: Add a model provider and its credentials.
/models: Pick the model for this session.
/agents: Pick the primary agent.
/mcps: See and toggle MCP servers.
/skills: Browse installed skills.
/init: Create or update AGENTS.md for this project.
/help: Show help inside DistilCode.

Configuration

Instructions and config files.

Project instructions

AGENTS.md: Project rules the agent reads at the start of every session: build and test commands, conventions, things to avoid. CLAUDE.md is read too.
~/.config/distilcode/AGENTS.md: Personal instructions applied to every project.

Config files

distilcode.json: Project config at the repository root, or in a .distilcode folder. Also read as distilcode.jsonc; opencode.json is still supported.
~/.config/distilcode/distilcode.json: Global config for providers, models, agents, permissions, MCP servers and keybindings.

Feedback

Found a bug or have an idea?

Report it on the bug report page. Include what you ran, what you expected and what happened. For anything else, use the contact page.

Download DistilCode

DistilCode documentation