This page collects day-to-day usage details that do not fit on the quickstart page.
The interface has four main areas:
- Startup header - shortcuts, loaded context files, prompt templates, skills, and extensions
- Messages - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
- Editor - where you type; border color indicates the current thinking level
- Footer - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
The editor can be replaced temporarily by built-in UI such as /settings or by custom extension UI.
| Feature | How |
|---|---|
| File reference | Type @ to fuzzy-search project files |
| Path completion | Press Tab to complete paths |
| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
| Copy response | Ctrl+X copies the last assistant message; in /tree, it copies the selected message |
| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
| Shell command | !command runs and sends output to the model |
| Hidden shell command | !!command runs without sending output to the model |
| External editor | Ctrl+G opens externalEditor, $VISUAL, $EDITOR, Notepad on Windows, or nano elsewhere |
See Keybindings for all shortcuts and customization.
Type / in the editor to open command completion. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.
| Command | Description |
|---|---|
/login, /logout |
Manage OAuth or API-key credentials |
/llama |
Download, load, and unload llama.cpp router models |
/model |
Switch models |
/scoped-models |
Enable/disable models for Ctrl+P cycling |
/settings |
Thinking level, theme, message delivery, transport |
/resume |
Pick from previous sessions |
/new |
Start a new session |
/name <name> |
Set session display name |
/session |
Show session file, ID, messages, tokens, and cost |
/tree |
Jump to any point in the session and continue from there |
/trust |
Save project trust decision for future sessions |
/fork |
Create a new session from a previous user message |
/clone |
Duplicate the current active branch into a new session |
/compact [prompt] |
Manually compact context, optionally with custom instructions |
/copy |
Copy last assistant message to clipboard |
/export [file] |
Export session to HTML or JSONL |
/import <file> |
Import and resume a session from a JSONL file |
/share |
Upload as private GitHub gist with shareable HTML link |
/reload |
Reload keybindings, extensions, skills, prompts, themes, and context files |
/hotkeys |
Show all keyboard shortcuts |
/changelog |
Display version history |
/quit |
Quit disco |
You can submit messages while the agent is still working:
- Enter queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
- Alt+Enter queues a follow-up message, delivered after the agent finishes all work.
- Escape aborts and restores queued messages to the editor.
- Alt+Up retrieves queued messages back to the editor.
On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in Terminal setup if you want disco to receive the shortcut.
Configure delivery in Settings with steeringMode and followUpMode.
Sessions are saved automatically to ~/.disco/agent/sessions/, organized by working directory.
disco -c # Continue most recent session
disco -r # Browse and select a session
disco --no-session # Ephemeral mode; do not save
disco --name "my task" # Set session display name at startup
disco --session <path|id> # Use a specific session file or session ID
disco --fork <path|id> # Fork a session into a new session fileUseful session commands:
/sessionshows the current session file and ID./treenavigates the in-file session tree and can summarize abandoned branches./forkcreates a new session from an earlier user message./cloneduplicates the current active branch into a new session file./compactsummarizes older messages to free context.
See Sessions and Compaction for details.
DisCo loads AGENTS.md or CLAUDE.md at startup from:
~/.disco/agent/AGENTS.mdfor global instructions- parent directories, walking up from the current working directory
- the current directory
Use context files for project conventions, commands, safety rules, and preferences. Disable loading with --no-context-files or -nc.
Replace the default system prompt with:
.disco/SYSTEM.mdfor a project~/.disco/agent/SYSTEM.mdglobally
Append to the default prompt without replacing it with APPEND_SYSTEM.md in either location.
On interactive startup, disco asks before trusting a project folder that contains project-local settings, resources, or project .agents/skills and has no saved decision for the folder or a parent folder in ~/.disco/agent/trust.json. Trusting a project allows disco to load .disco/settings.json and .disco resources, install missing project packages, and execute project extensions.
Before the trust decision, disco loads only context files, user/global extensions, and CLI -e extensions so they can handle the project_trust event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
Non-interactive modes (-p, --mode json, and --mode rpc) do not show a trust prompt. Without an applicable saved trust decision, they use defaultProjectTrust from global settings: ask (default) and never ignore those project resources, while always trusts them. Pass --approve/-a or --no-approve/-na to override project trust for one run.
If no extension or saved decision applies, defaultProjectTrust controls the fallback behavior. Set it to "ask", "always", or "never" in ~/.disco/agent/settings.json, or change it with /settings.
disco config and package commands use the same project trust flow, except disco update never prompts. Pass --approve to trust project-local settings for one command or --no-approve to ignore them.
Use /trust in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes ~/.disco/agent/trust.json only; the current session is not reloaded, so restart disco for changes to take effect.
Use /export [file] to write a session to HTML.
Use /share to upload a private GitHub gist with a shareable HTML link.
For upstream reference, Pi provides badlogic/pi-share-hf for publishing Pi sessions to Hugging Face datasets. It targets Pi session data and is not a supported DisCo session integration.
disco [options] [@files...] [messages...]disco install <source> [-l] # Install package, -l for project-local
disco remove <source> [-l] # Remove package
disco uninstall <source> [-l] # Alias for remove
disco update [source|self|disco] # Update disco only, or one package source
disco update --all # Update disco and packages; reconcile pinned git refs
disco update --extensions # Update packages only; reconcile pinned git refs
disco update --models # Refresh model catalogs only
disco update --self # Update disco only
disco update --extension <src> # Update one package
disco list # List installed packages
disco config # Enable/disable package resourcesThese commands manage disco packages and disco update can update the disco CLI installation. To uninstall disco itself, see Quickstart. disco config and project package commands accept --approve/--no-approve to trust or ignore project-local settings for one command. disco update never prompts for project trust.
See DisCo Packages for package sources and security notes.
| Flag | Description |
|---|---|
| default | Interactive mode |
-p, --print |
Print response and exit |
--mode json |
Output all events as JSON lines; see JSON mode |
--mode rpc |
RPC mode over stdin/stdout; see RPC mode |
--export <in> [out] |
Export a session to HTML |
In print mode, disco also reads piped stdin and merges it into the initial prompt:
cat README.md | disco -p "Summarize this text"| Option | Description |
|---|---|
--provider <name> |
Provider, such as anthropic, openai, or google |
--model <pattern> |
Model pattern or ID; supports provider/id and optional :<thinking> |
--api-key <key> |
API key, overriding environment variables |
--thinking <level> |
off, minimal, low, medium, high, xhigh, max |
--models <patterns> |
Comma-separated patterns for Ctrl+P cycling |
--list-models [search] |
List available models |
| Option | Description |
|---|---|
-c, --continue |
Continue the most recent session |
-r, --resume |
Browse and select a session |
--session <path|id> |
Use a specific session file or partial UUID |
--fork <path|id> |
Fork a session file or partial UUID into a new session |
--session-dir <dir> |
Custom session storage directory |
--no-session |
Ephemeral mode; do not save |
--name <name>, -n <name> |
Set session display name at startup |
| Option | Description |
|---|---|
--tools <list>, -t <list> |
Allowlist specific built-in, extension, and custom tools |
--exclude-tools <list>, -xt <list> |
Disable specific built-in, extension, and custom tools |
--no-builtin-tools, -nbt |
Disable built-in tools but keep extension/custom tools enabled |
--no-tools, -nt |
Disable all tools |
Built-in tools: read, bash, edit, write, grep, find, ls.
| Option | Description |
|---|---|
-e, --extension <source> |
Load an extension from path, npm, or git; repeatable |
--no-extensions |
Disable extension discovery |
--skill <path> |
Load a skill; repeatable |
--disco-no-builtin-skills |
Disable only bundled DisCo skills; keep other discovered and explicit skills |
--no-skills, -ns |
Disable all discovered skills; explicit --skill paths still load |
--prompt-template <path> |
Load a prompt template; repeatable |
--no-prompt-templates |
Disable prompt template discovery |
--theme <path> |
Load a theme; repeatable |
--no-themes |
Disable theme discovery |
--no-context-files, -nc |
Disable AGENTS.md and CLAUDE.md discovery |
Combine --no-* with explicit flags to load exactly what you need, ignoring settings. Example:
disco --no-extensions -e ./my-extension.ts| Option | Description |
|---|---|
--system-prompt <text> |
Replace default prompt; context files and skills are still appended |
--append-system-prompt <text> |
Append to system prompt |
--verbose |
Force verbose startup |
-a, --approve |
Trust project-local files for this run |
-na, --no-approve |
Ignore project-local files for this run |
-h, --help |
Show help |
-v, --version |
Show version |
Prefix files with @ to include them in the message:
disco @prompt.md "Answer this"
disco -p @screenshot.png "What's in this image?"
disco @code.ts @test.ts "Review these files"# Interactive with initial prompt
disco "List all .ts files in src/"
# Non-interactive
disco -p "Summarize this codebase"
# Non-interactive with piped stdin
cat README.md | disco -p "Summarize this text"
# Named one-shot session
disco --name "release audit" -p "Audit this repository"
# Different model
disco --provider openai --model gpt-4o "Help me refactor"
# Model with provider prefix
disco --model openai/gpt-4o "Help me refactor"
# Model with thinking level shorthand
disco --model sonnet:high "Solve this complex problem"
# Limit model cycling
disco --models "claude-*,gpt-4o"
# Read-only mode
disco --tools read,grep,find,ls -p "Review the code"
# Disable one extension or built-in tool while keeping the rest available
disco --exclude-tools ask_questionDisCo keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
For the full rationale, read the blog post.