Skip to content
Back to search

octogent

SkillWorks with Claude CodeGitHub

A thin orchestration dashboard over Claude Code for managing context, automation, and developer headspace. You need tentacles. 🦑

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hesamsheikh-octogent/badge.svg)](/listings/hesamsheikh-octogent)

HTML

<a href="/listings/hesamsheikh-octogent"><img src="/api/listings/hesamsheikh-octogent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<details> <summary><strong>Local development</strong></summary>

pnpm install
pnpm dev

This starts the API and web app for local development.

</details>

<details open> <summary><strong>Current install status</strong></summary>

Octogent is not published to the npm registry yet.

For local development:

pnpm install
pnpm dev

For a local global CLI install from a clone:

pnpm install
pnpm build
npm install -g .
octogent

The registry install flow `npm install -g octogent` will only work after the package is published.

</details>

On first run, **Octogent** creates the local `.octogent/` scaffold automatically, assigns a stable project ID, picks an available local API port starting at `8787`, and opens the UI unless `OCTOGENT_NO_OPEN=1` is set.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 187 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img width="1500" height="500" alt="Octogent header" src="./static/images/octogent-header.png" />
  3. <br/>
  4. <br/>
  5. <strong>too many terminals, not enough tentacles</strong>
  6. <br />
  7. <br />
  8. ![Last Update](https://img.shields.io/github/last-commit/hesamsheikh/octogent?label=Last%20Update&style=flat-square)
  9. [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  10. [![Node.js](https://img.shields.io/badge/Node.js-22+-5FA04E?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
  11. [![Follow on X](https://img.shields.io/badge/Follow%20on-X-000000?style=flat-square&logo=x)](https://x.com/Hesamation)
  12. [![Discord](https://img.shields.io/badge/Discord-Open%20Source%20AI%20Builders-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/vtJykN3t)
  13. </div>
  14. # Octogent
  15. It's really 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 doing documentation, another is touching the database, another is changing the API, and another is somewhere in the frontend. **Octogent** tries to fix that by giving each job its own <u>scoped context, notes, and task list</u>, while also making it possible for Claude Code to **spawn other Claude Code agents**, assign them work, and communicate with them.
  16. ## The Vision
  17. This repo is 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, not the final interface by themselves. The point is not to hide **Claude Code** behind abstractions. The point is to make *multi-agent work less chaotic for the developer* on a real codebase.
  18. ## Screenshots
  19. <div align="center">
  20. <table>
  21. <tr>
  22. <td><img src="./static/images/preview_1.jpg" alt="Screenshot 1" width="100%"/></td>
  23. <td><img src="./static/images/preview_2.jpg" alt="Screenshot 2" width="100%"/></td>
  24. </tr>
  25. <tr>
  26. <td><img src="./static/images/preview_3.jpg" alt="Screenshot 3" width="100%"/></td>
  27. <td><img src="./static/images/preview_4.jpg" alt="Screenshot 4" width="100%"/></td>
  28. </tr>
  29. <tr>
  30. <td><img src="./static/images/preview_5.jpg" alt="Screenshot 5" width="100%"/></td>
  31. <td><img src="./static/images/preview_6.jpg" alt="Screenshot 6" width="100%"/></td>
  32. </tr>
  33. </table>
  34. </div>
  35. ## What Octogent Does for You
  36. - **Creates tentacles as context layers** so agents can work with scoped markdown files instead of broad, messy chat context
  37. - **Uses `todo.md` as an execution surface** so tasks stay visible, trackable, and ready for delegation
  38. - **Runs multiple Claude Code terminals** so one developer can coordinate several coding sessions at once
  39. - **Spawns child agents from todo items** so parallel work has a concrete source of truth
  40. - **Supports inter-agent messaging** so workers and coordinators can report completion, blockers, and handoff notes
  41. - **Keeps agent-facing context in files** so the system is more durable than a single prompt thread
  42. - **Provides a local API and UI** for terminal lifecycle, persistence, websocket transport, and orchestration
  43. A **tentacle** is a folder under `.octogent/tentacles/<tentacle-id>/` that holds agent-readable markdown such as `CONTEXT.md`, `todo.md`, and any extra notes needed for that slice of the codebase.
  44. The octopus metaphor is literal: *one octopus, many tentacles, different work happening at the same time*.
  45. ## Tentacles
  46. A **tentacle** is a scoped job container. It gives one slice of work its own files, notes, and `todo.md` so the agent is not forced to reconstruct the entire codebase context from chat history.
  47. What it does:
  48. - keeps context local to one area such as documentation, database work, API changes, or frontend work
  49. - gives agents durable files they can read and update
  50. - provides a natural source for delegation through todo items
  51. For the full model, see [Tentacles](docs/concepts/tentacles.md) and [Working With Todos](docs/guides/working-with-todos.md).
  52. ## Context, Notes, and Task Lists
  53. In Octogent, a tentacle is not only a task bucket. It is also where the job keeps its local context. That can include notes about one part of the codebase, implementation details, handoff files, and a `todo.md` that tracks what still needs to happen. A Claude Code agent can read and update those files as the work moves forward.
  54. That means you can:
  55. - keep documentation, database, API, or frontend work separated into different job contexts
  56. - store the notes that help an agent understand that part of the codebase
  57. - spawn one agent for one specific item
  58. - break a larger job into multiple items
  59. - launch a swarm so several agents work through the list in parallel
  60. - use the files inside the tentacle as the shared source of truth for what is done and what is left
  61. For the full model, see [Tentacles](docs/concepts/tentacles.md) and [Working With Todos](docs/guides/working-with-todos.md).
  62. ## Claude Code Managing Claude Code
  63. One of the main ideas here is that **Claude Code** should not only be treated as a single terminal session waiting for a human prompt. In Octogent, one Claude Code agent can coordinate other Claude Code agents, assign them specific jobs, and exchange short messages with them while the human stays at the orchestration layer.
  64. This is different from Claude Code's subagent spawning, since it allows you to directly see and control what each worker agent is doing.
  65. That means Octogent is not just a dashboard for multiple terminals. It is also a way to structure parent-worker behavior around scoped tasks and shared context files.
  66. For the current model, see [Orchestrating Child Agents](docs/guides/orchestrating-child-agents.md) and [Inter-Agent Messaging](docs/guides/inter-agent-messaging.md).
  67. ## How It Works
  68. Octogent separates three concerns that usually get mixed together in a pile of terminals:
  69. 1. **Context** lives in `.octogent/tentacles/<tentacle-id>/`. `CONTEXT.md` explains the area, `todo.md` supplies executable work items, and extra markdown files hold notes or handoffs.
  70. 2. **Execution** lives in terminal records and PTY sessions managed by the local API. A terminal can attach to an existing tentacle, and several terminals can share one tentacle during swarm work.
  71. 3. **Isolation** is optional. Shared terminals run in the main workspace; worktree terminals run under `.octogent/worktrees/<worktree-id>/` on `octogent/<worktree-id>` branches.
  72. Deck reads the tentacle files directly, parses checkbox items from `todo.md`, and uses incomplete items to generate worker prompts. Claude hooks feed the API with agent state, transcript, and idle events so the UI can show more than raw terminal output.
  73. ## Quick start
  74. <details>
  75. <summary><strong>Local development</strong></summary>
  76. ```bash
  77. pnpm install
  78. pnpm dev
  79. ```
  80. This starts the API and web app for local development.
  81. </details>
  82. <details open>
  83. <summary><strong>Current install status</strong></summary>
  84. ```bash
  85. Octogent is not published to the npm registry yet.
  86. ```
  87. For local development:
  88. ```bash
  89. pnpm install
  90. pnpm dev
  91. ```
  92. For a local global CLI install from a clone:
  93. ```bash
  94. pnpm install
  95. pnpm build
  96. npm install -g .
  97. octogent
  98. ```
  99. The registry install flow `npm install -g octogent` will only work after the package is published.
  100. </details>
  101. On first run, **Octogent** creates the local `.octogent/` scaffold automatically, assigns a stable project ID, picks an available local API port starting at `8787`, and opens the UI unless `OCTOGENT_NO_OPEN=1` is set.
  102. ## Requirements
  103. - Node.js `22+`
  104. - `claude` installed for the supported agent workflow
  105. - `git` for worktree terminals
  106. - `gh` for GitHub pull request features
  107. - `curl` for the current Claude hook callback flow
  108. Startup fails if neither `claude` nor another supported provider binary is installed. The current docs only cover **Claude Code**.
  109. ## What persists
  110. - `.octogent/` keeps project-local scaffold and worktrees
  111. - `~/.octogent/projects/<project-id>/state/` keeps runtime state, transcripts, monitor cache, and metadata
  112. - `.octogent/tentacles/<tentacle-id>/` keeps the context files and todos that agents read
  113. PTY sessions survive browser reloads during the idle grace period, but they do **not** survive an API restart. Octogent marks previously running terminal records as `stale` on startup when it cannot reattach them to a live PTY session; use `octogent terminal list`, `stop`, `kill`, and `prune` to inspect and clean them up. Octogent caps live PTY sessions at 32 by default to protect the host; set `OCTOGENT_MAX_TERMINAL_SESSIONS` to a positive integer to tune that limit for larger orchestration runs.
  114. ## Docs
  115. - [Docs Home](docs/index.md)
  116. - [Installation](docs/getting-started/installation.md)
  117. - [Quickstart](docs/getting-started/quickstart.md)
  118. - [Mental Model](docs/concepts/mental-model.md)
  119. - [Tentacles](docs/concepts/tentacles.md)
  120. - [Runtime and API](docs/concepts/runtime-and-api.md)
  121. - [Working With Todos](docs/guides/working-with-todos.md)
  122. - [Orchestrating Child Agents](docs/guides/orchestrating-child-agents.md)
  123. - [Inter-Agent Messaging](docs/guides/inter-agent-messaging.md)
  124. - [CLI Reference](docs/reference/cli.md)
  125. - [Filesystem Layout](docs/reference/filesystem-layout.md)
  126. - [API Reference](docs/reference/api.md)
  127. - [Experimental Features](docs/reference/experimental-features.md)
  128. - [Troubleshooting](docs/reference/troubleshooting.md)
  129. - [Contributing](CONTRIBUTING.md)
  130. ## Contributor setup
  131. Octogent is not actively reviewing pull requests right now. If you still open one and any code was written with AI, disclose which coding agent and model were used. For contributor workflow and expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.