Octogent: a local dashboard that turns Claude Code sessions into scoped, file-backed workers
A thin orchestration dashboard over Claude Code for managing context, automation, and developer headspace. You need tentacles. 🦑
At a glance
- What is it?
- Octogent is an experimental MIT-licensed TypeScript tool that puts a local API and UI over multiple Claude Code terminals, giving each job a folder of markdown context and a todo.md that other agents can be spawned from. It is early, it assumes you already live inside Claude Code, and its value depends on whether you actually run several sessions at once.
- Who is it for?
- Adopt Octogent if you already run several Claude Code sessions on one repository and keep losing track of which session owns which part of the codebase; the tentacle folder plus todo.md model is a direct answer to that. Do not adopt it if you use one terminal at a time, or if you need a stable interface, since v0.1.0 is labelled experimental.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 148 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Octogent names: ten terminals and no memory of which one is doing what
The README opens with a concrete complaint. Having ten Claude Code sessions open at once is not fun, and switching between them while trying to remember each one's purpose gets blurry fast, especially when one agent is on documentation, another on the database, another on the API, and a fourth somewhere in the frontend. That is the failure Octogent targets, and it is a context failure rather than a throughput one. Nothing in the repository claims the agents are faster. The claim is that a developer coordinating several of them stops reconstructing intent from chat scrollback.
The intended user is a single developer working on a real codebase with more than one Claude Code session open. The README calls the project a personal exploration of what an AI coding environment might look like when terminal coding agents are treated as parts of a bigger orchestration layer. That framing matters for adoption. This is not a team platform with roles and permissions. It is one person's answer to their own terminal sprawl, published under MIT.
Tentacles, todo.md, and the three-way split between context, execution and isolation
The core unit is a tentacle, defined in the README as a folder under .octogent/tentacles/<tentacle-id>/ holding agent-readable markdown: CONTEXT.md to explain the area, todo.md to supply executable work items, and any extra notes or handoff files. The README describes three concerns that Octogent keeps apart. Context lives in those tentacle folders. Execution lives in terminal records and PTY sessions managed by the local API, and a terminal can attach to an existing tentacle, with several terminals sharing one tentacle during swarm work. Isolation is optional: shared terminals run in the main workspace, while worktree terminals run under .octogent/worktrees/<worktree-id>/ on octogent/<worktree-id> branches.
That third layer is the part worth pausing on. Worktree terminals give each worker its own checkout on a namespaced branch, which is the only mechanism in the described system that prevents two agents from writing to the same working tree. Shared terminals do not have that protection, so a swarm launched against one tentacle in shared mode is a set of processes editing the same files. The README does not say Octogent serialises those writes. It presents shared and worktree terminals as a choice, and the choice carries the concurrency risk.
The data flow is file-first. Deck, the UI, reads the tentacle files directly, parses checkbox items out of todo.md, and uses incomplete items to generate worker prompts. Claude hooks feed the API with agent state, transcript and idle events so the interface can show more than raw terminal output. So the loop is: you write or refine todo.md, Octogent turns unchecked boxes into prompts, a worker agent runs, and the checkbox state plus any notes it writes become the shared record of what happened. That is durable in a way a prompt thread is not, because it survives process restarts. It is also only as good as the discipline of keeping todo.md current.
Parent agents spawning workers, and how that differs from Claude Code subagents
Octogent's second idea is that one Claude Code agent coordinates others. The README states that a Claude Code agent can spawn other Claude Code agents, assign them work, and exchange short messages, with workers and coordinators reporting completion, blockers and handoff notes. The stated difference from Claude Code's own subagent spawning is visibility: Octogent lets you directly see and control what each worker agent is doing.
Whether that distinction holds in practice depends on how much of the worker's state the hooks actually surface. The README says hooks report agent state, transcript and idle events, which suggests the UI can render more than terminal scrollback, but it does not enumerate the event schema or say which hook events map to which UI states. Treat the visibility claim as the project's own description rather than a verified property. The inter-agent messaging is described as short messages for completion, blockers and handoffs, not a general RPC channel.
The delegation source of truth is deliberately narrow. Workers are spawned from todo items, so a job that is not written down as a checkbox is not delegable. That constraint is the design, not an oversight, and it is why the README keeps returning to todo.md as an execution surface.
Getting it running: pnpm install, pnpm dev, and the folder layout you have to create
The quick start in the README is short. Under local development it gives two commands:
pnpm install pnpm dev
The README says this starts the API and web app for local development. The badges pin Node.js 22 or later and TypeScript 5.8, so the runtime floor is explicit even though the install section is not. There is no published install path in the material beyond building from source, and no npm package name is given.
Configuration is filesystem-based rather than a config file. You create .octogent/tentacles/<tentacle-id>/ and put CONTEXT.md and todo.md inside it. If you want isolation, worktree terminals land under .octogent/worktrees/<worktree-id>/ on branches prefixed octogent/. The README references docs/concepts/tentacles.md, docs/guides/working-with-todos.md, docs/guides/orchestrating-child-agents.md and docs/guides/inter-agent-messaging.md, which are where the actual mechanics live. The README itself is a summary; the guides are the specification. Note that the supplied README is truncated mid-way through the quick start, so any additional setup steps after the local development block cannot be confirmed from this material.
Where Octogent is the wrong tool
The first limitation is stated by the project itself. v0.1.0 is marked experimental in the release list, and the README calls the repository a personal exploration. Interfaces at that stage move, and the README does not promise stability.
The second is scope. Octogent orchestrates Claude Code specifically. The topics list mentions codex, but the described mechanisms, hooks, skills and terminal spawning, are all framed around Claude Code sessions. If your agents are not Claude Code, the orchestration layer has nothing to attach to. This is not a general multi-agent framework.
The third is the shared-terminal case already noted. The README offers worktree isolation as optional, which means the default posture of several terminals on one tentacle is concurrent access to one working tree. If you are running a swarm on shared terminals, you are responsible for the conflicts.
The fourth is that the whole system depends on markdown hygiene. Deck generates worker prompts from incomplete checkboxes in todo.md. A stale todo.md produces stale prompts. Nothing described here reconciles a checkbox against what an agent actually did, so the file is a claim about state rather than a verified one. The README's own framing, that keeping context in files is more durable than a single prompt thread, is true about persistence and silent about correctness.
The alternative: Claude Code subagents and plain git worktrees
The obvious alternative is what you already have. Claude Code ships subagent spawning, and the README explicitly positions Octogent against it on one axis: Octogent lets you see and control each worker directly, while subagents are spawned inside a session. If your work fits inside one Claude Code session and you do not need a persistent external view of each worker, subagents plus a well-maintained CLAUDE.md get you most of the context discipline without a second process, a local API, a websocket transport, or a dashboard to keep running.
The second alternative is manual: run several terminals yourself and use git worktrees plus a notes file per area. That is essentially what Octogent automates, and doing it by hand costs nothing to install and nothing to upgrade. The difference is that you maintain the mapping between terminal, branch and notes yourself, and you have no parsed todo.md driving prompt generation. Octogent's contribution is the automation of that mapping and the checkbox-to-prompt step. If that step is not something you want, the manual version has fewer moving parts.
Maintenance, upgrade cost, and what the MIT licence means here
The repository is not archived and the last push recorded is 2026-04-20, the same timestamp as the v0.1.0 release. That means the first public release is also the most recent activity in the material, so there is no track record of upgrade cadence to reason about. Expect the API surface, the hook event handling and the tentacle folder layout to be the parts most likely to move, because they are the parts the README describes in the most detail and the parts other files depend on.
Running it means running a local API and a web app alongside your Claude Code terminals, plus whatever the hooks require. That is a persistent local process, not a one-shot CLI, so the upgrade cost is not just pulling new code. You will need to re-check hook wiring and the shape of .octogent/ between versions.
The licence is MIT, which permits commercial and private use and modification, and requires the copyright notice and permission notice to be included in copies or substantial portions. It provides no warranty. That is a permissive arrangement with minimal obligations, but it says nothing about whether the hooks you install modify Claude Code behaviour in ways your team's policies cover. That question is about your Claude Code configuration, not the licence, and it is worth answering before you wire Octogent into a repository you share.
Editorial conclusion
Adopt Octogent if you already run several Claude Code sessions on one repository and keep losing track of which session owns which part of the codebase; the tentacle folder plus todo.md model is a direct answer to that. Do not adopt it if you use one terminal at a time, or if you need a stable interface, since v0.1.0 is labelled experimental. Verify first that the Node 22 and pnpm prerequisites match your environment, read docs/concepts/tentacles.md and docs/guides/orchestrating-child-agents.md to confirm the parent-worker model fits how you delegate, and check whether the hooks the README mentions are documented for your Claude Code version before wiring anything into a real repository.
Community notes