Octogent
Coordinate multiple Claude Code sessions with scoped context, visible task lists, and controllable terminals.
The README discloses the local API, PTYs, persistence locations, worktrees, session cap, and cleanup commands, while the MIT file and repository social links provide basic attribution. Deductions apply because no least-privilege model or per-action confirmation flow is shown. Tests demonstrate reading Claude and Codex OAuth credentials, sending tokens to Anthropic/OpenAI services, and potentially rewriting Codex auth.json, but the supplied material does not document redaction, file permissions, consent, auditing, or complete retention boundaries. Frozen installation and CI offer some dependency discipline, but no audit, update policy, or vulnerability response is evidenced. Worktrees provide partial isolation and recovery, while terminal kills, agent file edits, and external PR effects lack comprehensive rollback guarantees.
The README, package metadata, CI, and tests are broadly consistent about Node 22, pnpm, Claude Code, PTYs, state detection, and usage retrieval. Required binaries are listed, and tests cover CLI/OAuth fallback, caching, rate limits, and missing credentials. Deductions reflect the unpublished npm package, PTYs that cannot survive API restarts, reliance on local tools and unofficial-looking service endpoints, and documentation currently limited to Claude Code. Failure messaging is unusually well evidenced, distinguishing missing credentials, insufficient scopes, unauthorized responses, rate limits, parsing failures, and background refresh states, justifying full marks for failure_messages.
The intended developer audience and documentation, database, API, frontend, and parallel-agent scenarios are clear; tentacles, shared terminals, and worktree modes provide reasonable adaptation. Boundaries identify the personal-exploration status, Claude-focused documentation, required binaries, and default 32-session cap. Trigger precision is deducted because state detection relies on terminal text markers and idle-time heuristics; tests cover chunking and ANSI output but do not establish a configurable structured protocol or false-positive handling. Environment requirements and tuning variables are documented, although Node 22, git, gh, curl, agent credentials, and local PTY support substantially constrain deployment.
The README has strong organization across concepts, operation, quick start, requirements, persistence, and a detailed documentation index. Installation status and clone-based local/global procedures are explicit, and limitations such as npm non-publication, PTY loss after restart, stale records, and Claude-only documentation are candidly stated. The complete MIT license agrees with package metadata, earning full license marks. Deductions apply because version 0.1.0 is not accompanied by a changelog, release history, or compatibility policy; terminology is mostly stable, but Deck appears without explanation. Examples are mainly commands, scenarios, screenshots, and links, with no FAQ content supplied. Maintenance responsibility is only weakly inferable from a personal account, social links, and the statement that pull requests are not actively reviewed.
File-based context, todo delegation, visible multi-terminal control, messaging, worktree isolation, and a local UI form understandable outputs with plausible marginal value over manually juggling terminals. Deductions apply because the evidence is primarily design prose, referenced screenshots, and tests of internal parsing and state logic; it does not substantiate completion quality, reduced coordination overhead, or orchestration performance at scale. Cost-benefit treatment is thin: usage display and a session cap are shown, but model-call expense, parallel-agent cost, disk use, credential exposure, and human supervision are not weighed against the claimed benefits.
Core claims are traceable to concrete paths, commands, and constraints in the README, with package.json, CI, and tests corroborating versions, the build chain, state detection, OAuth fallback, and error behavior. Deductions apply because implementation sources, the lockfile, linked detailed documentation, and screenshot contents are absent, leaving orchestration, messaging, terminal lifecycle, and worktree claims only partly checkable from the supplied material. The README separates vision, current installation status, and several limitations reasonably well, but promotional value claims are not paired with measurements or independent corroboration.
- The product reads local Claude/Codex OAuth credentials and may write refreshed Codex tokens back to auth.json; inspect implementation-level file permissions, log redaction, network destinations, and token retention before use.
- Agents can run terminals, modify a shared workspace, and execute todo items concurrently. Start in a low-privilege test repository with worktrees and require human confirmation and recovery procedures for commits, pushes, PRs, deletion, and kill operations.
- The npm package is not yet published and PTYs cannot be recovered after an API restart. Pin the reviewed revision and lockfile, and prepare cleanup procedures for stale sessions and uncommitted changes.
- State detection includes terminal-text and timeout heuristics; an idle or processing label in the UI should not be treated as proof that an agent completed work safely.
What does this agent do, and when should you use it?
Octogent is a local orchestration dashboard for supervising multiple Claude Code coding sessions rather than replacing the terminal agent itself. It organizes each job as a tentacle under `.octogent/tentacles/<tentacle-id>/`, containing `CONTEXT.md`, `todo.md`, and optional notes or handoff files. A local API manages terminal records, PTY sessions, persistence, and WebSocket transport, while the Deck UI reads task files and displays agent state, transcripts, and idle events. A coordinating Claude Code agent can turn unfinished todo items into worker prompts, launch child agents, and exchange completion, blocker, and handoff messages with them. Terminals can work in the shared project directory or use isolated Git worktrees under `.octogent/worktrees/<worktree-id>/`; project scaffolding stays in the repository while runtime state and transcripts live in the user's home directory. It is best suited to developers willing to run a local, Claude Code-centered tool and actively supervise several concurrent development streams.
Octogent starts a local API and web interface, then creates the project's .octogent/ scaffold, assigns a stable project ID, and selects an available API port beginning at 8787. Deck reads CONTEXT.md, todo.md, and supplementary Markdown files directly from each tentacle, parses checkbox items in todo.md, and uses unfinished items to construct child-agent prompts. The local API creates and manages Claude Code terminals and PTY sessions; several terminals may share a tentacle, or a terminal may run in an isolated worktree on an octogent/<worktree-id> branch. Claude hooks send agent state, transcript, and idle events back to the API, and the UI presents them over WebSocket transport. Agents can exchange short completion, blocker, and handoff messages, while runtime metadata, transcripts, and monitor cache persist under ~/.octogent/projects/<project-id>/state/.
- A solo developer handling documentation, database, API, and frontend changes concurrently can assign each area its own tentacle instead of tracking ten ambiguous terminal sessions.
- A technical lead breaking a large refactor into auditable units can maintain checkbox items in
todo.mdand launch workers from the unfinished entries. - A Claude Code user who wants human oversight can inspect and control each worker from one dashboard instead of relying solely on invisible in-session subagents.
- A developer running parallel experiments without putting every change in the main workspace can use worktree terminals backed by
octogent/<worktree-id>branches. - A user who frequently reloads or switches away from the browser can retain job context in tentacle files and review locally persisted state and transcripts.
What are this agent's strengths and limitations?
- Durable
CONTEXT.md,todo.md, and companion files provide inspectable shared context instead of making one chat transcript the sole source of truth. - It goes beyond terminal aggregation by letting one Claude Code agent assign work, launch visible child agents, and receive explicit handoff messages.
- Shared-workspace and Git-worktree terminal modes offer a concrete choice between fast collaboration and branch isolation.
- The local API, WebSocket UI, hooks, transcripts, and persisted runtime state provide more operational visibility than raw terminal output alone.
- A default cap of 32 live PTY sessions protects the host, with
OCTOGENT_MAX_TERMINAL_SESSIONSavailable for deliberate scaling.
- The documented workflow is centered on Claude Code, with no verified operating instructions for other model platforms or provider adapters.
- There is no npm release yet, so adopters must clone, install dependencies, build, and install the CLI from a local checkout.
- PTY sessions do not survive an API restart; records that cannot be reattached become
staleand require inspection or cleanup. - The local stack requires Node.js 22+, Claude Code, git, GitHub CLI, and curl, and some observability depends on Claude hooks.
- The project is not actively reviewing pull requests, creating uncertainty for teams that need upstream acceptance or timely maintainer feedback.
How do you install or deploy this agent?
The package is not yet published to npm, so npm install -g octogent does not currently work. Prerequisites are Node.js 22+, the claude binary, git for worktree terminals, gh for GitHub pull-request features, and curl for the current Claude hook callback flow. For local development:
git clone https://github.com/hesamsheikh/octogent.git
cd octogent
pnpm install
pnpm devTo install the CLI globally from the clone:
pnpm install
pnpm build
npm install -g .
octogentOn first launch, Octogent creates .octogent/, assigns a project ID, selects an available local port starting at 8787, and opens the UI. Set OCTOGENT_NO_OPEN=1 to suppress automatic browser opening.
How do you use this agent?
Run octogent from the target project; when developing Octogent itself, run pnpm dev from its repository. Create a job directory at .octogent/tentacles/<tentacle-id>/, describe its scope in CONTEXT.md, place checkbox tasks in todo.md, and add Markdown notes or handoff files as needed. Attach a terminal to that tentacle, then launch one worker for a specific item or start parallel workers from several unfinished items. Use Deck to monitor terminal output, agent state, and transcripts, and use inter-agent messages for completion reports, blockers, and handoffs. Shared terminals operate in the main workspace; choose a worktree terminal when branch-level isolation is required. The documented maintenance commands are octogent terminal list, stop, kill, and prune for inspecting and cleaning terminal records.
How does this agent compare with similar options?
Compared with Claude Code's built-in subagent spawning, Octogent is designed to let the developer directly see and control each worker while organizing parent-worker activity around tentacle files, todo entries, and explicit messages. It is also more than a multi-terminal dashboard: it adds scoped context, task delegation, persisted transcripts, and optional Git-worktree isolation around terminal lifecycle management.
FAQ
Can I install it directly from npm?
pnpm install and pnpm dev, or building a clone and running npm install -g ..Does it support the OpenAI API, Codex, or ChatGPT?
codex appears as a repository topic, no Codex, ChatGPT, or OpenAI API adapter, installation path, or working invocation is documented, so support is not verified.What survives a browser or API restart?
stale at startup.Can parallel workers overwrite one another's changes?
.octogent/worktrees/<worktree-id>/ on dedicated octogent/<worktree-id> branches.Where is data stored, and is a hosted service required?
.octogent/, while runtime state, transcripts, monitor cache, and metadata live under ~/.octogent/projects/<project-id>/state/. No mandatory hosted service is documented.