claudeers.
// Automation & Workflows

den

See, approve and steer all your Claude Code agents from one terminal screen.

// Automation & Workflows[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-agents#claude-code#golang#hyprland#omarchy#terminal#tui#automation◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
100/100
last commit 12 days ago
last release 12 days ago
releases 19
open issues 3
// star history

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.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/GlacierHubAB/den/releases
// or clone
git clone https://github.com/GlacierHubAB/den

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageGo

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Den

See, approve and steer all your Claude Code agents from one terminal screen.

Den's Fleet view: seven Claude Code agents, five of them in the orchestrator's tree of who directs whom, each with its role, task, model and context use, and the selected tech lead's details, critter, usage gauges and recent tool calls on the right.

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

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>.json for every live session, which Den treats as the source of truth (internal/discover). claude must be on PATH for the orchestrator and for spawned agents.
  • Go 1.26 (the go line in go.mod) to build from source.
  • A terminal that reports Shift+Enter (Den asks for it; Ctrl+J and Alt+Enter also insert a newline). Thumbnails of pasted images need the kitty graphics protocol and are skipped without it.
  • Hyprland for focusing an agent's terminal (Enter on an empty line, den focus) and for putting spawned terminals on your workspace. Without hyprctl the 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-app with xdg-terminal-exec, or xdg-terminal-exec alone, or $TERMINAL. Without one spawn_agent and open_terminal report 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. Without notify-send nothing is shown and nothing else changes.
  • ssh and scp only 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. Enter on 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

Den's Inbox: a waiting permission request from a backend developer agent to run go test, with Ctrl+Y allow, /always and Ctrl+N deny, above two finished turns from a technical writer and a reviewer.

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+Y allows 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, ~/.config or ~/.local, a .claude folder or .git (any repository), .githooks, .gitattributes, .gitmodules, .mcp.json, .gitconfig, .npmrc, .netrc, .tmux.conf, .vimrc, X session files (.xprofile, .xinitrc and the like), .pam_environment or a shell start-up file (.bashrc, .profile, .zshrc and 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/, a Makefile or package.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), or stuck.tool_failures tool calls (3) failed in a row (PostToolUseFailure; a tool you interrupt with Esc does 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.stalled minutes (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.
  • failed and stalled: the stuck items above.
  • without_den: Den only notifies while it runs. With this on, den hook turns 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

CommandDoes
/allow /y, /deny /n, /always /aanswer the waiting prompt
/open /o /focusfocus 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 /xclear the selected inbox item
/unread /ukeep the selected inbox item counted as new until opened or dismissed; again to mark it read
/copycopy the last command block in view (Orchestrator and Overview)
/close /killclose 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 /rrefresh 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, /reviewswitch view
/maptoggle the Fleet map
/orchestrator /orchopen the orchestrator; /orch new starts a fresh session, /orch restart restarts it
/project <name>, /project add <dir>, /project droppick, list or unlist a project
/mission <goal>, /pause, /resume, /stopmissions
/budget 2M, /budget $5, /budget offset, 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 /delremove the review comment under the cursor
/send, /send <Name>, /send orchestratorsend 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

KeyDoes
Tab / Shift+Tabnext / previous view (with @ typed, Tab completes the name)
Ctrl+Oopen 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 PgDnscroll the chat; half a screen in Review; five rows elsewhere
Entersend; 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+Jnewline
Ctrl+Y / Ctrl+Nallow / deny the waiting prompt (Overview: start / drop the proposed mission)
Ctrl+Ttoggle the Fleet map
Ctrl+Xclose the selected agent (Fleet, map, Inbox): a question in the inbox lists what would close, Ctrl+Y does it
Ctrl+Vpaste an image from the clipboard
Escclear the line; closes a proposal or an open mission; drops a review edit or range
Ctrl+Cquit

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.

KeyOn 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+Nanswer the card's permission, exactly as in the inbox
/openfocus 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:

SkillRolesRepository @ commitLicense
frontend-designfrontend, designanthropics/skills @ dbd4588f9e10Apache-2.0
test-driven-developmenttesting, codingobra/superpowers @ bb92a7774141MIT
verification-before-completioncodingobra/superpowers @ bb92a7774141MIT
diagnosing-bugscodingmattpocock/skills @ 49dd158d1076MIT
vulnerability-triage-brocardssecuritytrailofbits/skills @ 442fc9d6c89bCC-BY-SA-4.0
property-based-testingtestingtrailofbits/skills @ 442fc9d6c89bCC-BY-SA-4.0
ponytailcodingDietrichGebert/ponytail @ 2961b52fc1feMIT

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.

ShapeRuns as
▶ onceone dispatch to one agent; done when it reports back
↻ loopone agent iterates; after each pass Den asks the orchestrator whether the goal is met, and it re-dispatches until it is
⇶ fan-outa lead with children in parallel, repeated until the lead says done
⏲ scheduleDen 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:

TemplateShapeTeam
code-reviewfan-outa review lead on opus, a code reviewer and a security auditor on sonnet; read-only
bugfixloopa coding agent on sonnet, a code reviewer on opus
researchfan-outa research lead on opus, a web researcher and a codebase researcher on sonnet
docs-passoncea 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.

…view the full README on GitHub.

// 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.

15 views
★ 10 stars
unclaimed
updated about 1 month ago

// embed badge

den on Claudeers
[![Claudeers](https://claudeers.com/api/badge/den.svg)](https://claudeers.com/den)

// retro hit counter

den hit counter
[![Hits](https://claudeers.com/api/counter/den.svg)](https://claudeers.com/den)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how den connects across the ecosystem