DuckTerm

One workspace for your coding agents: live terminals, nested sessions, shared connectors, and project files.

Install · First session · Features · Mac app · How it works · Development

What is this?

Claude Code, Codex, and Copilot live in terminal tabs. Running several at once means alt-tabbing to find the one that's waiting on you, losing track of which branch each is on, and having no way to ask "what has that session actually done?"

DuckTerm launches each agent into a tmux-backed PTY it owns and renders it in the Mac app with xterm.js — a real terminal you type into, not a transcript viewer. Around the terminals it shows what a terminal can't:

• which session needs you right now (hook-driven state: busy / waiting / idle)
• context pressure per session — tokens used, model, and a "checkpoint or compact" warning before the window fills
• approvals as buttons — permission prompts resolve from the dashboard
• an Ask Oracle button — ask questions about all running sessions at once ("who's stuck?", "what has refactor-auth done so far?")

Sessions survive server restarts (tmux), run in isolated git worktrees when you want parallel attempts, and fork — including conversation forks for Claude Code.

Install

DuckTerm Lite is the public download. On Apple Silicon Macs running macOS 13+, download the app, unzip it, move DuckTerm Lite.app to Applications, and open it. Python, tmux, the dashboard and its local backend are included. No Homebrew, pipx or separate backend installation is required for the app.

Code and Full are available through the edition download forms on the DuckTerm website. Lite includes folders, workstreams, coding-agent sessions, forks, terminals, Shell, Messages and session status. Install and sign in to your chosen coding agent separately; Git is needed for Git workstreams. Your agents use their existing tools, environments and accounts.

For other platforms or CLI setup, see installation documentation.

Your first session

1. In the dashboard, choose New → New session.
2. Choose an installed agent and the project directory you want it to work in.
3. Launch the session and type your task into its terminal.
4. Use folders to organize agents, Messages to read their conversations, and Shell for project commands.

For agent event reporting, install hooks for the agent you use before launching new sessions. Run the applicable command in another terminal:

# Claude Code
duckterm install-hooks --agent claude-code --global
# Codex
duckterm install-hooks --agent codex --global

These commands update that agent's user-level configuration. Hook capabilities vary by runtime; Codex approval prompts must still be answered in its terminal. Run duckterm doctor to check dependencies, hooks, and server connectivity. For an app-only installation, use "/Applications/DuckTerm Lite.app/Contents/Resources/bin/duckterm" in place of duckterm in these commands. The app also makes that CLI available inside new DuckTerm agent terminals. It does not replace a CLI installed with pipx. See installation, upgrades, and troubleshooting for help.

Features

Terminals, first-class

• Every session is a live xterm.js terminal: type, paste, Ctrl-C, 5000 lines of scrollback. Six color themes, assignable globally, per folder, or per session.
• Launch with any of your installed oh-my-zsh prompt themes per session, without touching your .zshrc.

Fleet control

• Folders nest and drag; each folder opens as a grid — iTerm-style splits (drag a pane onto another's edge to restack), resize bars, a dock for collapsed sessions, a folder switcher.
• Stop is a pause (Resume relaunches — continuing the conversation for Claude Code); Archive is final; Delete requires a second click.
• Ask Oracle: one question, answered from a digest of every running session's state, goal, and screen.

The structured layer

• Messages view — the conversation rendered as HTML; select any span of a reply, attach a note, and it's sent back to the agent as a follow-up turn. Pin individual messages to revisit them from the strip above the terminal. Hover a pin icon for a short excerpt; click it to open the message. These pins survive restarts and retain a saved copy if the transcript changes.
• Sub-agent tree — Task-tool sub-agents nested under their parent, live.
• Worktrees & forks — launch into an isolated worktree per attempt; fork a session's git state or (Claude Code) its conversation; compare branches.
• AGENTS.md that learns — "Suggest from corrections" distills the feedback you've given agents (annotations, follow-up prompts) into proposed rules you review before saving.
• Installable skill kits — register a collection of skills/hooks/sub-agents (e.g. uv-suite) and install it into any project from the dashboard, with per-skill-kit option pickers and compatibility declarations. Contract: docs/harnesses.md.

Ducky for iPhone

Ducky shows this Mac's sessions in collapsible folders, with search and filters for active sessions and agents needing you. Finished and interrupted sessions remain visible; archived and merged sessions are hidden. Remote computers and other DuckTerm edition workspaces are separate.

In the Mac app, choose Pair iPhone…, scan the invitation and approve the phone with Mac authentication. Enable Allow conversations with agents to read Claude Code/Codex replies and send short messages. Existing pairings retain status-only access; create a new invitation to grant conversations. Permission prompts must still be answered on the Mac.

Messages queue until the agent has an empty prompt and nobody has typed in its terminal for two minutes. A queue receipt confirms storage on the Mac; Delivered confirms terminal delivery, not that the agent has read it. The queue expires after 15 minutes. An uncertain delivery is never automatically replayed. Restarting the backend cancels unsent queued messages.

The phone shows the latest 100 plain user/assistant messages, bounded to 256 KiB, from supported local transcripts. It refreshes while open. Keep DuckTerm open and use a network that permits phone-to-Mac connections; networks with client isolation can block pairing and refresh even when both devices have Wi-Fi.

Session inboxes

Agents can send persistent assignments to other sessions in their shared folder. Supported runtimes receive a task-end reminder for accepted, unanswered work. See inbox delivery and safeguards.

Backups

duckterm backup archives the database, checkpoints, and Claude/Codex transcripts. Use --to PATH for another local destination or --to gs://BUCKET/prefix for upload with your existing gcloud login. See backup and restore.

Shared connectors

Connectors can run on one shared host for local and remote agents. Provider credentials stay on that host; each agent machine enrolls once with a workspace certificate. See shared connector setup and enrollment.

Mac app

On Apple Silicon Macs running macOS 13+, download DuckTerm-Lite-macos-arm64.zip, unzip it, and move DuckTerm Lite.app to Applications. Its private Python, backend, tmux and hook tools are packaged together and updated with the app. Your installed Python and project virtual environments are unchanged.

The app opens the dashboard in a native window with a Dock icon and notifications. It starts Lite when needed, or connects to an existing Lite server. If another edition is running, the app explains how to switch while retaining sessions and settings. Existing installations keep their selected edition until you switch. It is signed with a Developer ID and notarized by Apple, so it opens without a security override. For Intel Mac, Linux, or Windows setup, see the installation documentation. See native build instructions for development.

How it works

One Python asyncio server (no framework), SQLite for history, tmux for session persistence. Agents report through their own hook systems (duckterm install-hooks) — session start, tool use, permission requests — which drive the state badges, approvals, and the sub-agent tree. The terminal is a binary WebSocket carrying raw PTY bytes to xterm.js; context-pressure numbers are read from the agent's transcript on disk. Everything runs on 127.0.0.1: GETs are loopback-gated, state-changing POSTs are token-gated.

DuckTerm is the terminal-forward sibling of Rubberduck, which watches agents you run in your own terminal tabs instead of owning the PTY. Install either or both.

Development

git clone https://github.com/utsavanand/duckterm.git
cd duckterm
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
(cd web && npm ci && npm run build)
DUCKTERM_INSTANCE=dev duckterm serve

To run the release gate, install the browser test runtime first:

(cd web && npx playwright install chromium)
scripts/gate.sh

Design docs: terminal-forward-design.md, structured-render-design.md.

License

FSL-1.1-MIT — the Functional Source License. You can read, run, modify, and redistribute DuckTerm for any purpose except offering a competing product; each release automatically becomes plain MIT two years after it ships.