Octogent takes a different approach to managing multiple AI agents by layering a local orchestration system on top of Claude Code. Instead of spawning opaque subagents, it uses file-based contexts called ’tentacles’ to isolate work areas and coordinate multiple Claude Code PTY terminals running simultaneously. This setup makes multi-agent development workflows visible, manageable, and persistent through scoped markdown files.
what octogent does and how it works
At its core, Octogent is a TypeScript project that acts as a local orchestration layer for Claude Code, the AI agent platform. It introduces the concept of ’tentacles’ — directories scoped to a specific context like API, frontend, docs, or database. Each tentacle contains context files such as CONTEXT.md, todo.md, and notes, which serve as durable, file-based context for the agents.
Octogent runs multiple instances of Claude Code in parallel using PTY terminals. It spawns child agents based on todo items defined in these tentacles, effectively implementing a parent-worker model. Agents communicate with each other through inter-agent messaging, allowing coordination between independent workstreams.
The architecture separates three concerns: context (stored in markdown files), execution (handled by PTY sessions), and optional isolation (using git worktrees to run terminals on separate branches). This separation provides flexibility in managing state and concurrency while maintaining observable workflows.
The system includes a local API and a web UI for managing terminal lifecycles, persistence, and orchestration. Unlike systems that treat agents as black boxes, Octogent structures the work through shared files, making the process transparent and easier to debug.
technical strengths and tradeoffs
What sets Octogent apart is its pragmatic approach to multi-agent orchestration. The use of scoped context directories (tentacles) with markdown files provides a simple yet effective way to isolate work areas and preserve state across agent restarts. This file-based persistence avoids complex distributed state management or database dependencies, keeping the architecture lightweight.
The parent-worker model orchestrated through todo items allows dynamic spawning of agents driven by explicit tasks. This makes the flow visible and manageable, contrasting with opaque subagent spawning where internal states and messages are hidden.
Running multiple Claude Code instances in PTY terminals simultaneously is a practical choice that leverages existing terminal multiplexing capabilities. It also enables direct control over lifecycle and output streams. However, this design ties the system to local environments and requires managing terminal state carefully.
The optional isolation using git worktrees is an interesting tradeoff. It allows running different agents on separate branches, minimizing context pollution and merge conflicts. But it adds complexity in managing git states and is relevant mostly for users familiar with git worktrees.
On the downside, Octogent currently depends on having Claude Code installed locally and does not support cloud or API-based agents out of the box. The npm package is not yet published, which limits easy installation and distribution.
Overall, the codebase is clean and modular, written fully in TypeScript with a clear separation of concerns. The README and documentation provide enough detail for developers to understand the architecture and extend the system.
quick start
Local development requires Node.js 22 or higher, Claude Code installed for agent workflows, git and GitHub CLI for worktree and PR features, and curl for Claude hooks.
Here are the commands for local development and CLI installation exactly as provided:
pnpm install
pnpm dev
This starts the API and web app for local development.
For a local global CLI install from a clone:
pnpm install
pnpm build
npm install -g .
octogent
The system automatically sets up the .octogent/ scaffold on first run, assigns a stable project ID, picks an available API port starting at 8787, and opens the UI unless disabled.
verdict
Octogent is relevant for developers exploring multi-agent AI workflows with Claude Code, especially those who want transparent, file-driven orchestration rather than black-box subagent spawning. Its architecture is well-suited for local development environments requiring explicit context isolation and inter-agent messaging.
That said, its reliance on local Claude Code binaries and PTY terminals limits deployment flexibility. The missing npm package and active contributor restrictions mean it’s currently more of a research or hobbyist tool than a polished production-ready framework.
If you’re experimenting with multi-agent workflows and want to see how explicit context isolation via files can enable visible and manageable agent orchestration, Octogent is worth a look. For production or cloud-based setups, you’ll need to watch for future developments or consider complementary tools.
Related Articles
- Inside agents: a granular multi-agent orchestration system with PluginEval quality assurance — Explore agents, a Python-based multi-agent orchestration repo featuring 184 AI agents, 78 plugins, and a three-layer Plu
- Flowise: visual low-code AI agent builder with a modular TypeScript monorepo — Flowise offers a visual drag-and-drop low-code platform to build AI agents and LLM apps, with a Node.js backend and Reac
- elizaOS: a TypeScript monorepo for building and deploying AI agents — Explore elizaOS, a TypeScript monorepo for AI agents with CLI and web UI. Build and deploy agents fast or extend with pl
→ GitHub Repo: hesamsheikh/octogent ⭐ 702 · TypeScript