
den
See, approve and steer all your Claude Code agents from one terminal screen.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up den (release-binary project) into my current project. Found on https://claudeers.com/den Repo: https://github.com/GlacierHubAB/den Homepage/docs: https://den.glacierhub.io Detected install method: release-binary → inspect the README Category: automation. Platforms: cli, api, desktop, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/GlacierHubAB/den/releases
git clone https://github.com/GlacierHubAB/den
// compatibility
| Platforms | cli, api, desktop, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Go |
Den
See, approve and steer all your Claude Code agents from one terminal screen.

Den is a small terminal UI that finds the Claude Code sessions already running
in your terminals, shows who they are (the agent-badge critter, role and task),
streams everything that needs your answer into one inbox, and lets you talk to
one agent with an @mention or to an orchestrator that speaks to all of them.
It also draws who directs whom, keeps standing goals as missions, and shows what
each agent changed as a diff you can comment on and send back to the agent,
and adds up what the work cost. Over ssh it shows the agents on your other
machines in the same Fleet, inbox and cost totals, and answers their requests
from here (Remote agents, docs/REMOTE.md).
Den is Linux software. It reads /proc and ~/.claude/sessions, brings
terminals to the front through Hyprland, and starts new ones through
xdg-terminal-exec. See Requirements for what works without
Hyprland.
Contents
- Install · Requirements · On Omarchy · Quick start
- Views: Overview, Fleet, Inbox, Review, Orchestrator
- Notifications · Events for scripts
- The command line · Keys
- Orchestrator · Dispatch cards
- Who directs whom · Spawning agents and teams · Closing agents · Bringing agents back · Skills for roles
- Overview, projects and missions · Templates
- Cost
- Review · Worktrees in Review · The agent badge
- Remote agents · Text from outside Den · docs/REMOTE.md
- Configuration · Files Den writes
- Troubleshooting · Den, Herdr and OpenRig · Contributing · License
Install
From source
The repository uses a git submodule (mods/agent-badge, the agent-badge mod
that Den embeds in its binary). Clone with it, or the build has nothing to
embed:
git clone --recurse-submodules https://github.com/GlacierHubAB/den
cd den
# already cloned without it? git submodule update --init
make build # ./den, stamped with the version from git describe
make install # builds into $PREFIX/bin/den, PREFIX defaults to ~/.local
go install …/cmd/den@latest does not work: the badge mod lives in the
submodule, which a Go module download does not include.
make test runs go vet ./... and the test suite against a scratch
XDG_STATE_HOME, so it never touches your own Den state.
From a release
Tagged releases carry static Linux binaries, den_linux_amd64 and
den_linux_arm64, the THIRD_PARTY_LICENSES notices and a SHA256SUMS file
covering all three. Download the binary for your machine and the checksum file
into one folder, then:
sha256sum -c --ignore-missing SHA256SUMS
chmod +x den_linux_amd64
mkdir -p ~/.local/bin && mv den_linux_amd64 ~/.local/bin/den
den version
Releases after v0.3.1 also carry a build provenance attestation, which says the binary was built by Den's release workflow from the tagged commit:
gh attestation verify den_linux_amd64 --repo GlacierHubAB/den
make release builds the same files into dist/; pushing a v* tag on main
runs it on GitHub Actions (see docs/RELEASING.md). Only
Linux binaries are built.
Requirements
- Linux, amd64 or arm64. Den reads the process tree from
/proc(internal/procs), so it does not run on macOS or Windows. - Claude Code 2.1.289 or newer. That is the version that writes
~/.claude/sessions/<pid>.jsonfor every live session, which Den treats as the source of truth (internal/discover).claudemust be onPATHfor the orchestrator and for spawned agents. - Go 1.26 (the
goline ingo.mod) to build from source. - A terminal that reports
Shift+Enter(Den asks for it;Ctrl+JandAlt+Enteralso insert a newline). Thumbnails of pasted images need the kitty graphics protocol and are skipped without it. - Hyprland for focusing an agent's terminal (
Enteron an empty line,den focus) and for putting spawned terminals on your workspace. Withouthyprctlthe Fleet, Inbox, Review, orchestrator and hooks still work; focus reports that no window was found. herdr panes are focused too when the agent runs inside one. - git 2.38 or newer for the merge check in Review (
git merge-tree --write-tree); the rest of Den does not need it. - A terminal launcher for spawning:
uwsm-appwithxdg-terminal-exec, orxdg-terminal-execalone, or$TERMINAL. Without onespawn_agentandopen_terminalreport an error (internal/spawn/spawn.go). notify-send(libnotify) for desktop notifications. Clicking one to focus the agent works on omarchy-shell (Omarchy 4), mako and swaync, and through a middle click on dunst. Withoutnotify-sendnothing is shown and nothing else changes.sshandscponly for remote hosts; Den uses your own ssh config and keys.- Hooks (
den install-hooks) for the inbox, permission answers, history and the hierarchy. Without them Den still lists and messages agents. - The agent-badge mod (
den install-mods) for roles, tasks and the 5-hour and weekly gauges. Optional: names and critters match with or without it.
On Omarchy
Den is built on and for Omarchy, and that is where every part of it works. On Omarchy:
- Spawned agents open the way Omarchy opens a terminal. Den runs
setsid uwsm-app -- xdg-terminal-exec --dir=<dir> -- claude …, the same launch as Omarchy's terminal keybinding, so the window is your default terminal and is detached from Den (internal/spawn/spawn.go). - They land on the workspace you are on. Den records the active Hyprland
workspace before it launches and moves the new window there if it opened
elsewhere (
internal/hypr). - Enter focuses the agent's window through
hyprctl, matching Ghostty's one-process-many-windows by title and directory. - Colours follow the current Omarchy theme, read from
~/.local/state/omarchy/current/theme/colors.toml(internal/theme).
Install it the usual way: download a release binary into ~/.local/bin
(already on Omarchy's PATH), or build it with make install (Go 1.26 or
later), then run den install-hooks once. Den ships no keybinding of its own;
to give it a key, bind omarchy-launch-or-focus-tui den in your Hyprland
bindings.
Other Linux desktops work too, without the window placement (see
Requirements). Den does not run on macOS or Windows: it reads
/proc.
Quick start
den install-hooks # once; wires Den into ~/.claude/settings.json (backed up first)
den install-mods # once; puts the bundled agent-badge mod into ~/.claude/skills
den # the TUI
Hooks and the mod apply to Claude Code sessions started after installing them. Existing sessions show up in the Fleet at once but only report prompts and turns once restarted.
den install-hooks adds one entry per event for SessionStart, SessionEnd,
UserPromptSubmit, Notification, Stop, PostToolUse, PreToolUse
(matcher AskUserQuestion), PermissionRequest, StopFailure and
PostToolUseFailure, each running den hook. Installing twice replaces Den's
old entries, so run it again after upgrading Den; den uninstall-hooks removes
them. CLAUDE_CONFIG_DIR moves the settings file Den edits.
Commands
den the TUI
den list [-json] what Den sees, for scripts and debugging
den focus mossy focus an agent's terminal by name, session id or pid
den explain mossy how Den arrived at that agent's name, status, window…
den send mossy "rebase on main first" message an agent from a script; --wait for its turn to end
den send mossy@devbox "…" the same for an agent on a remote host, through the running Den, after your ^Y in its inbox (no --wait)
den wait mossy --until done block until an agent is idle, needs you, or done
den ask "who is blocked on what?" one orchestrator turn from a script
den events -json follow the event stream, one JSON object per line
den events headless: print hook events as they arrive
den install-hooks wire Den into Claude Code's hooks
den uninstall-hooks undo
den skills the skills Den installed, for which project or agent, from where
den skills catalogue the vetted skills catalogue: repo, pinned commit, license, why
den skills match "ui designer" what the catalogue offers a role
den skills remove frontend-design ~/code/site remove what Den installed
den remote add devbox add a host to the Fleet over ssh (docs/REMOTE.md)
den remote list [-json] the hosts, their policy, state and agents
den remote status devbox the read-only checks again; also: install, remove, disable, enable
den install-mods put the bundled agent-badge mod into ~/.claude/skills
den mods what ships in this binary and where it is loaded from
den uninstall-mods undo
den config the config file path and the settings in effect
den config init write a documented ~/.config/den/config.toml
den version
den mcp and den hook are run by Claude Code, not by you.
Views
The tab row reads Overview Fleet Inbox Review. Tab and Shift+Tab cycle
through them. The orchestrator has no tab: Ctrl+O opens it and brings you
back, and sending plain text opens it too. Its state sits beside the keycap on
the tab row.
- Overview: one project at a time, its agents on the left and its missions on the right. See Overview, projects and missions.
- Fleet: agents grouped by state (needs you, working, idle, gone) or by the
tree that directs them, each with critter, role, task, repo, branch and
context usage. A details pane shows the selected agent's animated critter,
context and usage gauges, the chain of command and recent activity.
Enteron an empty line brings that agent's terminal to the front. - Inbox: every permission request, plan review, question and finished turn from every session. See below.
- Review: what each agent changed, as a diff. See Review.
- Orchestrator: the chat with the agent that knows the fleet.
Inbox

With the hooks installed, each item is a permission, a plan review, a question
or a finished turn; Den adds its own questions, to close agents, to install
skills or to reopen agents after a restart. Waiting permissions and plans can
be answered from Den: Ctrl+Y allows and Ctrl+N denies the waiting one,
/always allows it and the same again this session (see below), /open focuses the
terminal, /dismiss clears an item, and /unread keeps the selected item
counted as new until you open or dismiss it (/unread again marks it read).
Finished turns are appended to ~/.local/state/den/history.jsonl (the newest
inbox.history, 100 by default, come back on restart). The request shows the
whole command or edit the permission is about. A request taller than the pane
scrolls inside it (↑ ↓, PgUp PgDn) under a marker that says how many
lines are left, and Ctrl+Y, /always or a typed answer waits until you have
scrolled to its end. In another view, Ctrl+Y answers only a request that
view shows whole, as the Fleet view's Details pane can; otherwise it opens the
Inbox on that request to be read there first, and Ctrl+Y again answers it.
Ctrl+N never waits.
What /always allows from then on, for that agent's session only (an agent
on a host is told apart by its host as well), kept in
memory until Den exits (the line that confirms it says which):
- a command: that exact command only. A command with shell operators,
substitutions, redirections or several lines (
;,&,|,$(, a backtick,<,>) takes no/always;Ctrl+Yallows it once. - a file edit (
Write,Edit,MultiEdit,NotebookEdit): edits by that tool inside the agent's working directory, never outside it, never through a symlink that leads out, and never of a file whose change runs code or raises trust: anything under~/.ssh,~/.configor~/.local, a.claudefolder or.git(any repository),.githooks,.gitattributes,.gitmodules,.mcp.json,.gitconfig,.npmrc,.netrc,.tmux.conf,.vimrc, X session files (.xprofile,.xinitrcand the like),.pam_environmentor a shell start-up file (.bashrc,.profile,.zshrcand the like). An agent working in your home directory, or above it, gets no edit rule at all. Such an edit, or one outside, is asked about as usual, and takes no/always. Inside the working directory a rule does cover files other tools run later, such as.envrc,.vscode/, aMakefileorpackage.json. An agent on a remote host gets no edit rule at all: its paths and symlinks cannot be checked from here, so each edit there is asked about. WebFetch: fetches from the same host.- an MCP tool: that tool of that server, never the whole server.
- any other tool: every call of that tool.
- a plan or a question: nothing; each is answered on its own.
Claude Code shows its own dialog in the agent's terminal at once, beside
Den's hold, so a request can always be answered there too; whichever answers
first counts. Answered or dismissed in the terminal first, the inbox item
closes at once and takes no Ctrl+Y or Ctrl+N. Den holds a request only
while you are not at that terminal: if the agent's window is focused, or you
switch to it, Den lets go and the terminal dialog is the only one, as it is
when hooks.permission_wait (580 s) runs out or Den is not running.
A plan (claude --permission-mode plan) is approved from Den like a
permission: Ctrl+Y is the dialog's "Yes, manually approve edits", so the
agent leaves plan mode for the mode it had before and starts on the plan;
Ctrl+N sends it back to keep planning, with a note that you denied it from
Den. Claude Code ignores a plain allow for a plan, so Den's hook answers with
the plan's own call, which Claude Code 2.1.289 takes; a plan call Den cannot
answer that way is left to the terminal and says so. Plans are approved one
at a time: /always does not answer a plan, as the dialog has no "always"
for plans either.
Answering an agent's questions
Off by default. With answer_questions = true under [hooks] in the config
(restart Den after changing it), a question an agent asks with Claude Code's
AskUserQuestion tool waits in the inbox as well as in its terminal: the
question, its header, its numbered options with their descriptions, and
"Question 2 of 3" when it asks several. On the Inbox view, select it and type
an option's number then Enter; for a question that takes several answers,
type several numbers (1 3). Anything else you type is your own answer, as
the dialog's "Type something" row takes it; put a number meant as text in
quotes ("3"). /answer <text> does the same from any view. A call with
several questions takes them one at a time, the answers so far listed above
the next one, and the agent hears back only once all are answered. Ctrl+Y
does not answer a question; Ctrl+N leaves it to the terminal.
The terminal dialog stays usable the whole time, and whichever you answer
first counts: answered or dismissed (Esc) in the terminal, the inbox item
clears. Den lets go after hooks.permission_wait (580 s, inside the hook's
600 s timeout), when you are at that terminal, or at once when Den is not
running; the question is then the terminal's alone. Den never answers on its
own.
This relies on undocumented Claude Code behaviour (a PermissionRequest
hook that allows the call with the answers added to its input), checked
against Claude Code 2.1.289. A later version may ignore such an answer; the
terminal dialog then stays and works as usual. No new hook is needed: it uses
the PermissionRequest hook den install-hooks already sets up.
Two kinds of item say an agent may be stuck. Neither ever counts as "needs you":
- failed: a turn ended on an API error (
StopFailure: rate limit, overload, login, billing), orstuck.tool_failurestool calls (3) failed in a row (PostToolUseFailure; a tool you interrupt withEscdoes not count). The item names the error type or the tool, never the command or its output. A new prompt, or a tool call that works, resolves it. - stalled: an agent has been working for
stuck.stalledminutes (20) with no hook event. A long build looks the same, so this is a hint to look, not a verdict. Any hook event from that agent resolves it.
Notifications
Den sends a desktop notification (through notify-send) when a permission,
plan or question starts waiting on you, and one reminder if it is still
waiting after notify.remind minutes (10). A notification reads like "Mossy
Lemur needs your permission": the agent's name and the kind of request, never
the command, a path, a prompt or file text; for an agent on a remote host,
"Mossy Lemur on devbox needs your permission". Clicking it brings that agent's
terminal to the front, as den focus does (for a remote agent it opens Den;
there is no window here to raise). That uses the notification's
default action: omarchy-shell (Omarchy 4), mako and swaync run it on a click,
dunst on a middle click; on a server without actions the click does nothing.
There is no notification for an agent whose terminal is the focused window, or while Den's own window is focused (when Den can tell: Ghostty runs all its windows in one process, so there it cannot), and none for the orchestrator's own traffic.
The rest are off by default, each with its own switch under [notify]:
done: an agent finished. Only the top of a branch notifies, an agent nobody in the fleet directs, or one the orchestrator does, and only once nobody under it is still working. Workers finishing for a lead stay quiet.failedandstalled: the stuck items above.without_den: Den only notifies while it runs. With this on,den hookturns Claude Code's own permission and input notices into a desktop notification when no Den is listening. There is nothing to click then.
DEN_NOTIFY=off turns every notification off.
Events for scripts
den hook appends every event to ~/.local/state/den/events.jsonl, one JSON
object per line with a version field and metadata only (kind, session, agent
name, time; never a command, prompt or file text). While Den runs it also
appends the events of remote hosts, each with a host field
(the host's label; absent for this machine). den events -json follows
it, den wait <agent> --until idle|needs-you|done blocks on it, and the [on]
config section runs a command per event kind, for example to push to your
phone. The stream and den wait work without Den running; the stalled and
still_waiting events and [on] commands come from a running Den. The
schema, exit codes and the environment [on] commands get are in
docs/EVENTS.md.
Messages you send to an agent arrive in its session the way messages from other Claude Code sessions do, with a first line saying they come from you via Den. While you are at that agent's terminal Den holds the message and delivers it when you leave, so it never lands under something you are typing.
The command line
The line at the bottom is always open. Type to ask the orchestrator, @Name …
to message one agent (Tab completes the name; @Name@devbox for one on a remote host), /help for commands. It grows
with what you type, one row for a short message and more as text wraps (by
display width, so wide characters count double) or you add line breaks, up to
a third of the screen; past that it scrolls inside itself and keeps the cursor
line in view. Nothing you type or paste is cut off. The panes above shrink to
make room.
Images travel with a message. Paste or drag an image file (a path, a file://
URL or several lines of them) and it becomes a chip, [Image #1], in the text;
Ctrl+V takes an image straight from the clipboard (saved under
~/.local/state/den/attachments/). When the message goes out the chip reads
[Image #1: /full/path.png], so the receiving session can open the file. If
the terminal answers Den's kitty-graphics query, a thumbnail is drawn next to
each chip. Delete a chip from the text and its image is left out.
Slash commands
| Command | Does |
|---|---|
/allow /y, /deny /n, /always /a | answer the waiting prompt |
/open /o /focus | focus the selected agent's terminal |
/answer <text> | answer the agent's question waiting in Den: an option's number, several for a multi-select, or your own words (with hooks.answer_questions) |
/dismiss /x | clear the selected inbox item |
/unread /u | keep the selected inbox item counted as new until opened or dismissed; again to mark it read |
/copy | copy the last command block in view (Orchestrator and Overview) |
/close /kill | close the selected agent (also one on a remote host, /close Name@devbox); /close idle every idle one; /close idle 1h those idle at least that long (30m, 2h, 1d); /close <name>, <name>; --force includes working agents and kills what does not stop |
/reopen <name>, /reopen --fork <name> | reopen an agent Den has seen in the last two weeks with claude --resume; --fork opens a copy of its conversation under a new session id |
/protect <Name>, /unprotect <Name> | keep an agent out of every close; /protect alone lists what is protected |
/flag <Name>: <note>, /unflag <Name> | mark an agent as holding context: a bulk close lists it without selecting it |
/rescan /r | refresh now (in Review, reload the diffs) |
/remote, /remote connect <label>, /remote retry <label> | list the remote hosts with their state; retry one now, applying a raise in remotes.toml after showing it (connect) or not (retry) (see Remote agents) |
/overview /missions, /fleet, /inbox, /review | switch view |
/map | toggle the Fleet map |
/orchestrator /orch | open the orchestrator; /orch new starts a fresh session, /orch restart restarts it |
/project <name>, /project add <dir>, /project drop | pick, list or unlist a project |
/mission <goal>, /pause, /resume, /stop | missions |
/budget 2M, /budget $5, /budget off | set, show (/budget alone) or remove the budget on the open or selected mission |
/template, /template <name> <target or goal>, /template save <name> | list the mission templates, start a proposal from one, save the open mission as one |
/delete /del | remove the review comment under the cursor |
/send, /send <Name>, /send orchestrator | send review drafts to their agents, to one agent, or those no live session can take to the orchestrator |
/merge [<Name>], /cleanup [<Name>] | in Review, ask to merge the selected agent's worktree branch, and to remove its worktree |
/help /?, /quit /q /exit |
Keys
| Key | Does |
|---|---|
Tab / Shift+Tab | next / previous view (with @ typed, Tab completes the name) |
Ctrl+O | open the orchestrator, press again to go back |
← → | move between panes; on Overview switch project; in Fleet fold and unfold a branch |
↑ ↓ | select, or scroll in the focused pane |
PgUp PgDn | scroll the chat; half a screen in Review; five rows elsewhere |
Enter | send; with an empty line, focus the selected agent's terminal (Overview: open the mission; chat: expand the card; Review: edit the comment under the cursor) |
Shift+Enter, Alt+Enter, Ctrl+J | newline |
Ctrl+Y / Ctrl+N | allow / deny the waiting prompt (Overview: start / drop the proposed mission) |
Ctrl+T | toggle the Fleet map |
Ctrl+X | close the selected agent (Fleet, map, Inbox): a question in the inbox lists what would close, Ctrl+Y does it |
Ctrl+V | paste an image from the clipboard |
Esc | clear the line; closes a proposal or an open mission; drops a review edit or range |
Ctrl+C | quit |
Review adds Shift+↑ ↓ to extend a selection and mouse support: click a work,
file or line, drag or shift-click for a range, wheel to scroll.
On the Orchestrator and Overview views Den owns the mouse too, because the
terminal's own selection runs across the whole row and would take the agents
pane and the borders along with the chat. Drag inside the chat or the mission
pane to select that pane's text only; letting go copies it. Click a command
block (the lines with a bar down the left) to copy the whole block, or type
/copy for the last one in view. The wheel scrolls. Copies go through OSC 52
(the terminal's clipboard escape) and through wl-copy when it is installed.
Esc drops the highlight. The terminal's own selection is still there: hold
Shift while dragging in Ghostty. The Fleet and Inbox views never capture the
mouse.
Orchestrator
The orchestrator is a headless Claude Code session Den starts on your first
plain-text message. It has six tools: ListAgents and SendMessage, plus
four Den gives it through its own MCP server (den mcp): spawn_agent,
open_terminal, close_agent and propose_skills; the last two only ever
ask you (see Closing agents and Skills for roles). It gets a fresh roster of
the fleet with every message, so it can answer "who is blocked on what?" or
relay "tell Mossy to rebase first". It cannot approve anything; you do that in
the inbox.
Its turns are billed like any other session. It uses sonnet unless the config
file or DEN_ORCHESTRATOR_MODEL says otherwise ("off" keeps Claude Code's
default). Only Den's MCP server is loaded into it (--strict-mcp-config); your
own MCP servers never are. A watchdog names a silent turn, restarts it once and
resends what it owes.
Each message has its speaker's name on the line above it, so the text uses the pane's full width.
The chat persists: every entry and card state is appended to
~/.local/state/den/orchestrator.jsonl and restored on launch (newest 500).
The orchestrator resumes its previous session; if that fails, Den starts a fresh
one and replays the last exchanges.
Guidance
guidance under [orchestrator] gives the orchestrator text of yours on how
to shape its answers. It is off unless you set it: "i-have-adhd" is the
i-have-adhd skill (v0.4.1, MIT),
shipped inside Den with four edits so it never hides what waits on you, never
answers for you, never counts as an approval and never trims where text came
from (internal/orch/guidance/i-have-adhd). An absolute path names a file of
your own instead. Den never fetches guidance over the network and never sends
it to a host. It drops a leading frontmatter block and refuses, with a note,
text over 8192 bytes after that, a file that does not read, is not yours, is
writable by others, is a symlink, has other hard links or lies in Den's state
folder, /proc, /sys, /dev or a kernel pseudo filesystem, and text with
control, bidi or invisible characters.
Nothing loads until you approve it. The first time, and whenever the text's
SHA-256 changes, the inbox asks, showing the whole text and its hash; Ctrl+Y
counts once you have read it to the end. Den then records that hash, and only
that, in ~/.local/state/den/guidance.json. Approved text goes into the
orchestrator's prompt in a <human_guidance> block after Den's own rules,
which it cannot relax or override. Den reads the key again every few seconds:
turning it off, or text that fails its checks, takes it out of the prompt once
the orchestrator is idle, and turning it on or changing it asks first and,
once you approve, puts it in once the orchestrator is idle. A turn in progress
is never cut short: the orchestrator resumes its session with the new prompt
at your next message. Other keys leave the approval alone. A process running as your user can change the config, the
file and the approval together, so Den's checks guard against mistakes and
other users, not against your own processes.
den ask from the command line starts a fresh orchestrator and doesn't load
guidance.
Dispatch cards
When the orchestrator hands a brief to an agent, that agent's turn shows up in the chat as a card the agent owns: its avatar and colour, the role chip, the brief, and a state chip through queued, working, needs you, done or failed. While it works the card shows the latest tool call from the hook stream; done, it collapses to the agent's last message in one sentence with call and file counts. With two or more cards live, a strip at the top of the pane keeps them in view. Everything on a card comes from the agent's own hooks and transcript, never from the orchestrator's retelling.
| Key | On a focused card |
|---|---|
↑ ↓ | move between cards; past the last one the chat follows its tail again |
Enter (empty line) | expand to the agent's full turn, with diffs and output |
→ | open the agent in the Fleet; ← comes back to the card |
Ctrl+Y Ctrl+N | answer the card's permission, exactly as in the inbox |
/open | focus the agent's terminal |
Who directs whom
Agents hand work to each other over Claude Code's session messaging, so the
fleet is a tree, not a list. Den learns the edges from traffic it already sees:
a dispatch card is an edge from the orchestrator; a peer message arriving at an
agent (the UserPromptSubmit hook carries the sender) puts the receiver under
the sender, unless the receiver sits above the sender, in which case it is a
report back; an agent the orchestrator spawned is its child from the start.
Edges are appended to ~/.local/state/den/edges.jsonl and come back on
restart; a child keeps its newest parent and drops out of the tree when its
session is gone.
In the Fleet every tree sits in its own section, the orchestrator's first, with
guides between parent and child, directs n on a parent and what the branch
needs rolled up (1 needs you). ← folds the selected branch and → unfolds
it. The details pane shows the chain of command (you › orchestrator › Mossy Lemur) and a directs list with each child's brief and state. Ctrl+T or
/map swaps the pane for a map: one column per level from you to the leaves;
↑ ↓ walk it, ← goes to the parent and → to the first child.
In the chat, a card whose agent handed work on grows a line per child, and its
state says needs you · via <child> when something deeper down is waiting on
you; Ctrl+Y / Ctrl+N on it answer the child's request. Inbox items from an
agent inside a tree carry a via orchestrator › … line.
Spawning agents and teams
Ask the orchestrator for a new agent ("start an agent in ~/code/site that fixes
the login redirect") and it opens your default terminal in that directory with
claude --name <peer> running and its brief as the first prompt. The brief
arrives introduced as coming from the orchestrator on your behalf and asks the
agent to report back when done or blocked. The agent appears in the Fleet like
any other, and the orchestrator tells you its critter name. "Open a terminal in
~/code/site" gives you a plain shell the same way.
The terminal is launched the way Omarchy's own keybinding does it (setsid uwsm-app -- xdg-terminal-exec --dir=…), so it is detached from Den. Den records
your active workspace first and moves the new window there if it landed
elsewhere. If Claude Code has never worked in the folder, it asks you to trust
it in that terminal first; nothing happens until you answer. Set spawn = false under [orchestrator], or DEN_ORCHESTRATOR_SPAWN=off, to take the two
tools away.
A model per agent. spawn_agent takes a model: haiku for small,
mechanical, well-specified tasks, sonnet for ordinary building, writing and
fixing, opus for work that needs judgment (design, architecture, review,
leading others). The orchestrator picks by the task. Its spawn note says which
(▶ starting an agent in ~/code/site on opus · …), and once the session
registers the note becomes that agent's dispatch card.
A worktree per agent. spawn_agent takes worktree: true, or a name.
The agent is then started with claude --worktree <name>, so Claude Code gives
it a git worktree of its own under <repo>/.claude/worktrees/<name> on a new
branch worktree-<name>, and parallel agents in one repository do not edit
the same files. With true the name is the agent's peer name (with a number
added if that folder already exists). The folder must be in a git repository
that has a commit; otherwise spawn_agent says so and starts nothing. The
agent's brief is extended with its branch and the instruction to commit there
and leave merging to you. A lead can give each of its people a tree the same
way. By default Claude Code branches from the repository's default branch on
the remote; its worktree.baseRef setting changes that. To carry gitignored
files such as .env into every new worktree, use Claude Code's own
.worktreeinclude file. Den has no per-repository setup command. When a
session exits with changes or commits in its worktree, Claude Code asks whether
to keep or remove it; an untouched worktree is removed without asking, and a
crashed session's stays. Den never removes one by itself (see Review).
Leads staff their own work. Every agent the orchestrator starts gets Den's
MCP server too, so it has spawn_agent itself, pre-approved. A lead's brief
names the roles under it with their models and parts; it starts them in their
own terminals, they report to the lead, and the lead reports up when the piece
is done. Ask for "a team" and the orchestrator starts one lead on opus and
leaves the rest to it. Den learns each of those spawns from the lead's own hook
stream (PostToolUse on spawn_agent), so the Fleet draws the tree as it
grows, and the lead's card stays working · waiting on 3 agents between turns
until nobody under it is at work.
Closing agents
Ctrl+X on an agent, or /close, asks before anything happens: a question
lands in the inbox listing exactly what would close, one line per agent
with its process id and the terminal window Den matched to it (or "no
window found, only the process ends"), and Ctrl+Y carries it out, Ctrl+N
keeps everything. /close idle clears every idle agent in one question;
/close Mossy Lemur, Snug Capybara names them. The question warns when an
agent's checkout has uncommitted changes (which files), and when an agent
directs others, who stay open unless also selected.
The rules, enforced whatever asked: an agent that is working or waiting on
you is refused unless you add --force; the orchestrator, Den itself and
anything Den runs inside are never closed; an agent not in the fleet is
refused by name; the window Den runs in is never closed. Agents close one at
a time, half a second apart. Each gets a graceful stop (SIGTERM) and a short
wait; only --force sends SIGKILL to one that does not stop, and nothing is
forced from the orchestrator's side. Only the agent's own process is
signalled, never its terminal. A terminal Den opened for the agent runs it
as its command, as a Ghostty process of its own with a window class Den
chose (io.glacierhub.den.<peer>, recorded in Den's state with the
agent's session), and closes with it. Den closes a window itself only when
it is still open after the agent ended, is still the one window with the
class recorded for that session, is run by the agent's terminal, and has
nothing else running in it (no shell in another tab, no second claude):
never a window of an agent Den did not spawn, never one matched by title or
folder, never the window in front or its own. The question says,
agent by agent, which window closes and how, or why Den will not close it.
Closed agents leave Den's state at once: their open inbox items are
resolved, they drop out of the tree, and the roster rescans.
/close idle 1h picks the agents that have been idle for at least that long.
Idle time is measured from the agent's last activity, which Den takes from
Claude Code's own session file: the moment the session last changed between
busy and idle (statusUpdatedAt), that is, when its last turn started or
ended; a session that has not reported a change yet counts from its start.
Den does not use the transcript's last write for this, because Claude Code
appends to the transcript when messages arrive, which is not use. An agent
whose last activity is unknown is never treated as stale. The same time is
LastActive in den list -json.
Some agents must survive a bulk close. /protect <Name> keeps an agent out
of every close, even by name, until /unprotect; the list is
~/.local/state/den/protected.json, which also takes paths (an agent whose
working directory, edited repositories or task involve one of them is
protected) and flagged agents. /flag <Name>: <note> marks an agent as
holding context you may still need: a bulk close shows it as "Holds context,
not selected" with the note, and only /close <Name> includes it. The
question lists what was skipped and why, so the list is always exact.
The orchestrator has the same door, close_agent: "kill the idle agents we are
not using" or "close what has not been used for an hour" (idle_for: "1h")
becomes the same question in your inbox, marked as its request with its
reason, protected agents skipped and flagged ones unselected, and it only
hears what you decided. It cannot force.
Bringing agents back
Den keeps a snapshot of every live agent in ~/.local/state/den/roster.json:
its session id, working directory, peer name, critter name, role, model,
who directs it, its mission, whether Den started it, its private skills
folder if it has one, and when Den last saw it. The file is rewritten
atomically when the fleet changes, and otherwise at most once a minute to keep
the last-seen times current.
When Den starts and agents that were live when it last stopped are gone (after
a reboot, say), one question lands in the inbox: Restore 3 agents?, one line
per agent with its name, role, model and folder, who directed it, its mission,
when Den last saw it, and how many tokens of conversation it would reload with
an estimated cost at its model's cache-write rate from the price table (see
Cost). Ctrl+Y reopens them, each in a new terminal on your workspace, the
way spawned agents start: claude --resume <id> with the same peer name,
model and skills folder, and Den's tools again for agents Den started.
Ctrl+N leaves them closed, and later restarts do not ask about them again.
Nothing reopens without Ctrl+Y.
The question leaves out agents you closed through Den (/close, Ctrl+X or
the orchestrator's close_agent) and agents that ended on their own while Den
was running, unless they ended within two minutes of Den's own last write,
which is how a shutdown looks. Agents whose conversation is no longer on disk
are left out too.
A resumed session keeps its session id, so it takes its old place in the tree
and its mission. Den puts each reopened agent back under the agent that
directed it once both are running again. /reopen <name> asks the same
question for one agent, closed or ended; /reopen --fork <name> works on a
running agent too and opens a copy of its conversation under a new session
id, which Den records so the copy takes the original's place in the tree.
restore.ask = false in the config, or DEN_RESTORE=off, turns the restart
question off; the roster is still kept for /reopen.
Skills for roles
Den ships a small, vetted catalogue of Claude Code skills (SKILL.md folders)
and offers the ones that fit an agent's role. Nothing is installed until you
press Ctrl+Y on a question in the inbox that lists each skill with its
repository, pinned commit, license and why it fits; Ctrl+N declines.
The catalogue is internal/skills/catalogue.json, built into the binary. Every
entry names a GitHub repository, a full commit SHA (never a branch), an
allowed license, its role tags, a one-line reason, what was checked before it
was admitted, and every file with its SHA-256. den skills catalogue prints it.
It holds seven skills from five repositories:
| Skill | Roles | Repository @ commit | License |
|---|---|---|---|
| frontend-design | frontend, design | anthropics/skills @ dbd4588f9e10 | Apache-2.0 |
| test-driven-development | testing, coding | obra/superpowers @ bb92a7774141 | MIT |
| verification-before-completion | coding | obra/superpowers @ bb92a7774141 | MIT |
| diagnosing-bugs | coding | mattpocock/skills @ 49dd158d1076 | MIT |
| vulnerability-triage-brocards | security | trailofbits/skills @ 442fc9d6c89b | CC-BY-SA-4.0 |
| property-based-testing | testing | trailofbits/skills @ 442fc9d6c89b | CC-BY-SA-4.0 |
| ponytail | coding | DietrichGebert/ponytail @ 2961b52fc1fe | MIT |
The writing, devops and research tags have no skills yet. Roles are free text
("coding agent", "ui designer", "sysadmin"), so Den matches them word by word
to the tags coding, frontend, design, writing, testing, security, devops and
research, and offers at most four skills; a role with no known word gets
nothing. den skills match "<role>" shows what a role would be offered. A
request that names skills (skills on spawn_agent or propose_skills) can
also have a catalogue skill past those four, if its tags fit the role.
Two ways in. spawn_agent takes a role: Den offers the matching skills
for that agent only and waits for your answer before starting it. On Ctrl+Y
they go into a folder of Den's own, ~/.local/state/den/skills/agents/<peer>-<time>/.claude/skills,
and the agent is started with claude --add-dir on it, so no other session
sees them; on Ctrl+N the agent starts without them. propose_skills offers
a role's skills to a project (an agent already running, or a folder you
name): they go into <project>/.claude/skills, where every Claude Code
session in that project finds them. A session that started before that folder
existed needs /reload-skills. The orchestrator offers skills when it starts
an agent with a role, or when you ask; a lead can pass a role to the agents it
starts.
What Den checks at install. It looks the skills up again in its own
catalogue (a request can only name skills whose tags fit the role), downloads each file
from raw.githubusercontent.com/<repo>/<commit>/…, and refuses the skill if
any file's size or SHA-256 differs from the catalogue, if any markdown file's
frontmatter sets hooks or allowed-tools, if it runs a shell command when
it loads (!`cmd` or a ```! block), or if SKILL.md names a different
skill. It never replaces a folder that is already there, writes no file
executable, and installs nothing into ~/.claude/skills. Skills whose folder
carries no license get their repository's license file copied in beside them.
Den runs nothing a skill ships.
Provenance and removal. Every install is recorded in
~/.local/state/den/skills.json: skill, repository, commit, license, scope,
project or agent, path, date, who approved (your user, in Den) and who asked.
den skills lists them. den skills remove <skill> [<project | peer | path>]
deletes the files Den installed, keeping any file changed since, removes the
skill's folder once it is empty, and drops the record.
Overview, projects and missions
The Overview tab, first in the row, shows one project at a time. Projects are
the repositories agents work in, found through the files their transcripts say
they edited plus session folders that are checkouts. An agent serving a live
mission is also listed on that mission's project, even from a checkout of its
own such as a scratch clone. The strip under the tabs lists the projects with
a count of agents on each. ← → or /project <name> switch,
the pick is remembered, and the Review tab follows it. A folder nobody works in
yet is listed with /project add <dir> (its repository root when it is inside
one) and stays listed, empty, until /project drop.
A mission is a standing goal: a purpose in one sentence, constraints that ride
on every dispatch, and what done looks like, or "standing" for one that never
ends. Type the goal on the Overview command line (or /mission <goal>) and the
orchestrator answers with a proposal: the mission rewritten, done-when,
constraints it inferred, the agents it means to reuse, the team it means to
start (roles as a tree, each with the model it picked), and the shape it chose
with one line of reasoning. Ctrl+Y starts it, Ctrl+N drops it, typing
refines it, Esc keeps it for later. Nothing runs before Ctrl+Y. When the
run starts, the orchestrator spawns only the roles that report to it; each lead
starts its own people.
| Shape | Runs as |
|---|---|
▶ once | one dispatch to one agent; done when it reports back |
↻ loop | one agent iterates; after each pass Den asks the orchestrator whether the goal is met, and it re-dispatches until it is |
⇶ fan-out | a lead with children in parallel, repeated until the lead says done |
⏲ schedule | Den fires a run on the cadence (every 30m, daily 08:30, weekly mon 09:00, or a five-field cron line); each run is a once or a fan-out |
Den drives the runs: it asks the orchestrator to dispatch, tags the resulting
cards with the mission, notices when they settle, and asks again when the shape
calls for another pass. Enter on a mission opens it: the fields, a line per
run with its progress or summary, then the mission's conversation, where the
agents the orchestrator dispatched work inline as dispatch cards, in the order
they were sent, just as in the Orchestrator chat. A dispatch made while you
talk about a finished mission shows there too. /pause holds the next run,
/resume lets it go, /stop ends the mission and keeps its history. Missions
persist in ~/.local/state/den/missions.jsonl; the project pick and pinned
projects in overview.json beside it.
Templates
A template is a mission's shape and team saved under a name: the purpose with a
blank ({target}) for what it is about, done-when, constraints, the shape, and
the roles as a tree, each with its model. Four ship in the binary:
| Template | Shape | Team |
|---|---|---|
code-review | fan-out | a review lead on opus, a code reviewer and a security auditor on sonnet; read-only |
bugfix | loop | a coding agent on sonnet, a code reviewer on opus |
research | fan-out | a research lead on opus, a web researcher and a codebase researcher on sonnet |
docs-pass | once | a technical writer on sonnet, an editor on haiku |
/template lists them. /template code-review ~/code/demo-app puts the
template's proposal on the Overview at once and asks the orchestrator to adapt it
to the target; it may change the team or the wording, and says what it changed.
A folder as the first word of the target picks that project. It is the usual
proposal card: Ctrl+Y starts it, Ctrl+N drops it, typing refines it, and
nothing runs before Ctrl+Y. The roles keep their words ("security auditor",
"technical writer"), so the vetted skills that fit a role are offered when the
agent is started, for you to approve, as for any other agent.
/template save <name> keeps the shape and team of the pending proposal or of
the open or selected mission (a name is lower-case letters, digits and
hyphens; a built-in's name is refused). Yours live in
~/.config/den/templates.json (beside config.toml, so DEN_CONFIG moves it):
a JSON list with the fields above, name, about and mission as the
minimum, which you can edit by hand. An entry with the name of a built-in
replaces it; an entry that is not valid is skipped; a file that does not parse
is reported on the list and never overwritten. Templates are data, with no
conditions or scripts. The orchestrator is told the template names with every
message, so "start a code review of ~/code/demo-app" can point you to one.
Cost
Den adds up the tokens in each session's transcript, exactly: every assistant message counts once (Claude Code writes a message once per content block, so the repeats are skipped), cache reads and writes are kept apart, and a session's subagents, which Claude Code keeps in files beside the session's own, are shown as a separate figure. A transcript is read once and then only what was appended.
// faq
What is den?
See, approve and steer all your Claude Code agents from one terminal screen.. It is open-source on GitHub.
Is den free to use?
den is open-source under the MIT license, so it is free to use.
What category does den belong to?
den is listed under automation in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/den)
// retro hit counter
[](https://claudeers.com/den)
// reviews
// guestbook
// related in Automation & Workflows
The API to search, scrape, and interact with the web at scale. 🔥
🌐 Make websites accessible for AI agents. Automate tasks online with ease.
Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop