Octogent: A Multi-Terminal Orchestration Dashboard for Claude Code Sessions

The Problem: Managing Many Simultaneous Agent Sessions

Running a single Claude Code session on a codebase is straightforward. Running ten simultaneous sessions, with one agent working on documentation, one on database changes, one on API routes, and another on the frontend, creates a different kind of problem: keeping track of what each session is doing, what context it has, and how its output relates to the other sessions. The terminal multiplier approach of opening multiple terminal windows or tmux panes does not help because each session's context lives only in its chat history.

The README opens with this observation directly: it is not fun to have ten Claude Code sessions open at once, constantly switching between them and trying to remember what each one was supposed to do. Things get blurry fast when one agent is touching the database, another is changing the API, and another is somewhere in the frontend. Octogent addresses this by giving each job its own scoped context, notes, and task list in a persistent file structure, and by providing a local UI for monitoring and coordinating the sessions.

This is a different problem than Claude Code's built-in subagent spawning, which creates child sessions that the parent session manages through its own API. Octogent is a developer-facing orchestration layer that lets the human stay at the top of the coordination hierarchy while multiple Claude Code agents work in parallel.

Tentacles: Scoped Job Containers with Files

The core abstraction in Octogent is the tentacle: a folder under .octogent/tentacles/<tentacle-id>/ that holds agent-readable markdown files. Each tentacle has a CONTEXT.md that explains the area of the codebase the agent should work in, a todo.md that tracks what still needs to happen, and any additional markdown files with notes or handoff information.

The octopus metaphor in the name is meant to be read literally: one octopus, many tentacles, different work happening at the same time. A tentacle is not just a task bucket; it is also the job's local context. The agent assigned to the documentation tentacle reads CONTEXT.md to understand the scope and writes to todo.md to track progress. When the human needs to understand what that agent has done, the files are readable directly without reviewing the terminal transcript.

Tentacle isolation is optional. Shared terminals run in the main workspace. Worktree terminals run under .octogent/worktrees/<worktree-id>/ on octogent/<worktree-id> branches, which isolates their git state from the main workspace. This matters for agents that make code changes; you can review their output in a separate branch before merging rather than having all agents write to the same working tree.

How Octogent Coordinates Agents

Octogent separates context, execution, and isolation into three distinct layers. Context lives in the .octogent/tentacles/ file structure. Execution lives in terminal records and PTY sessions managed by the local API server. Isolation is the optional worktree layer.

The Deck component of the UI reads tentacle files directly and parses checkbox items from todo.md. Incomplete checkbox items become the source for worker prompts when the user delegates a task to a Claude Code agent. Claude hooks feed the API with agent state, transcript, and idle events so the UI shows more than raw terminal output; it can show when an agent is waiting for input versus actively working.

Parent-worker relationships are a first-class concept. A Claude Code agent running as a coordinator can spawn other Claude Code agents, assign them specific jobs from the tentacle's todo.md, and exchange short messages with them. The human stays at the orchestration level while the coordinator agent manages the workers. This is documented in the guides for orchestrating child agents and inter-agent messaging in the docs/ directory.

The local API starts on port 8787 by default, with Octogent picking an available port starting from that number if 8787 is occupied. The UI opens automatically on first run unless OCTOGENT_NO_OPEN=1 is set.

Installing Octogent from Source

Octogent is not currently published to the npm registry. The README notes explicitly that npm install -g octogent will only work after the package is published. For now, local development requires cloning the repository.

For development:

pnpm install
pnpm dev

This starts the API server and the web application for local development. For a global CLI install from the clone:

pnpm install
pnpm build
npm install -g .
octogent

The application requires Node.js 22 or later. The claude binary must be installed and accessible on PATH for the Claude Code agent workflow. The git and gh binaries are required for worktree terminals and GitHub pull request features. The curl binary is required for the current Claude hook callback flow. Octogent fails to start if claude is not installed.

On first run, Octogent creates the .octogent/ scaffold in the project directory, assigns a stable project ID, and picks an available port starting at 8787. Runtime state is stored in ~/.octogent/projects/<project-id>/state/. The package manager is pnpm at version 10.4.1.

Current Limitations and Known Gaps

The release is explicitly labeled experimental in the v0.1.0 GitHub release notes from 2026-04-20. The README describes the project as a personal exploration of what an AI coding environment might look like rather than a finished product. Several features noted in the documentation point to guides that describe the intended design rather than fully implemented functionality.

The registry installation path is not available. The documentation covers Claude Code as the supported agent workflow; other providers are mentioned in passing but not fully documented. The README notes that pull request features require the gh CLI and that worktree terminals require git, but it does not describe how to recover from a failed worktree setup.

As a comparison, Claude Code's own subagent spawning lets one agent spawn others through the API without a separate orchestration dashboard. The difference is visibility: Octogent provides a UI where the human can see the state of each agent at a glance and intervene directly, while Claude Code's subagent model is designed to run without human intervention. Octogent is better suited when you want to stay in the loop across many parallel sessions; native subagent spawning is better when you want a single autonomous workflow.

Maintenance State and License

The last push to the repository was on 2026-04-20, which is five months and eight days before this article was written. The repository has one GitHub release at v0.1.0, which matches the current version in package.json. The license is MIT.

The Biome linter and formatter configuration, the vitest test setup, and the monorepo structure with apps/ and packages/ suggest this is a properly organized project rather than a quick prototype. CONTRIBUTING.md and AGENTS.md are present. The Discord invite link in the README points to an active community channel, which suggests the project has users beyond the author.

The Node.js engine requirement in package.json is 22 or later, and the package manager is pnpm at version 10.4.1. These are specific and up-to-date constraints, which indicates the project is developed against a current toolchain. Whether development continues past the current pause is unknown; monitor the repository if you are considering adoption.

Editorial conclusion

Octogent is worth evaluating if you regularly run three or more simultaneous Claude Code sessions on a single codebase and find that tracking what each session is doing becomes the limiting factor in your workflow. The v0.1.0 release is explicitly labeled experimental in the GitHub release notes. It is not published to npm, requires a local build, and the documentation notes that the registry install will only work after the package is published. Before adopting it, clone the repository and run pnpm dev to confirm the setup works for your Node.js version and worktree configuration. The MIT license places no restrictions on use or modification.

Frequently asked questions

Official sources

1. hesamsheikh/octogent on GitHub
2. Issues
3. License: MIT
4. README
5. Releases