@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/apps/web/vite.config.ts

@@ -0,0 +1,22 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+const apiProxyTarget = process.env.OCTOGENT_API_ORIGIN ?? "http://127.0.0.1:8787";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: {
+      "/api": {
+        target: apiProxyTarget,
+        changeOrigin: true,
+        ws: true,
+      },
+    },
+  },
+  test: {
+    environment: "jsdom",
+    setupFiles: "./tests/setup.ts",
+    include: ["tests/**/*.test.tsx"],
+  },
+} as never);

package/apps/octogent/bin/octogent

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/api/cli.js";

package/apps/octogent/biome.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "files": {
+    "ignore": ["node_modules", "dist", "coverage"]
+  }
+}

package/apps/octogent/docs/concepts/mental-model.md

@@ -0,0 +1,79 @@
+# Mental Model
+
+This page is for the exact model behind Octogent. The README is the pitch. This page is the boundary map.
+
+## The main pieces
+
+- the **developer** defines the jobs and reviews the output
+- a **tentacle** holds the local context for one job
+- a **terminal** is one live Claude Code session
+- a **worker** is a terminal assigned to a narrower piece of work
+- a **parent** is a terminal coordinating one or more workers
+- a **channel** is a short-lived coordination path between terminals
+
+## Tentacle vs terminal
+
+These are different things.
+
+- a **tentacle** is a folder with agent-readable files
+- a **terminal** is a running session
+
+Multiple terminals can point at the same tentacle. That matters for swarm work, because several workers may need the same local context while still remaining separate sessions.
+
+## Tentacle vs worktree
+
+These are also different things.
+
+- a **tentacle** is the context layer
+- a **worktree** is the git isolation layer
+
+A tentacle can be used with:
+
+- a shared-workspace terminal
+- a worktree-backed terminal
+
+The tentacle decides *what the job is about*. The worktree decides *where the code changes happen*.
+
+## What belongs in files
+
+The durable source of truth should live in files inside the tentacle.
+
+That includes:
+
+- context about the area
+- notes and handoff information
+- the current task list in `todo.md`
+
+If another agent needs to understand the job later, the important information should already be there without depending on one old chat thread.
+
+## What belongs in runtime state
+
+The runtime owns:
+
+- live terminal sessions
+- websocket transport
+- UI state
+- transcripts
+- message delivery state
+
+That data helps the app run, but it is not the same thing as the durable job context.
+
+## How delegation is supposed to work
+
+The expected flow is:
+
+1. the developer or a parent agent defines a job boundary
+2. the tentacle files capture the local context
+3. `todo.md` breaks the job into executable items
+4. one or more child terminals take those items
+5. workers report status through files and short messages
+6. the parent or human reviews the result
+
+If the boundary is vague, the orchestration gets worse. Octogent helps organize work, but it does not rescue a poorly defined job.
+
+## What the project is actually trying to prove
+
+- terminal coding agents can be treated as building blocks inside an orchestration layer
+- file-based context is more reliable than trying to keep everything inside one long conversation
+- one Claude Code session can coordinate other Claude Code sessions in a visible way
+- simple task lists and short messages are enough for some useful multi-agent workflows

package/apps/octogent/docs/concepts/runtime-and-api.md

@@ -0,0 +1,60 @@
+# Runtime And API
+
+Octogent runs as a local API with a local web UI on top.
+
+## Runtime shape
+
+```mermaid
+flowchart TD
+  Browser[Browser UI] --> HTTP[HTTP routes]
+  Browser --> WS[WebSocket terminal stream]
+  HTTP --> Runtime[Terminal runtime]
+  WS --> Runtime
+  Runtime --> PTY[PTY sessions]
+  Runtime --> Files["Project and global state"]
+  Runtime --> Hooks[Claude hook ingestion]
+```
+
+## What the API does
+
+- starts and restores terminal metadata
+- serves the web UI when bundled assets are available
+- manages PTY-backed terminal sessions
+- creates worktrees for isolated terminals
+- persists UI state and conversation state
+- reads tentacle files and todo progress
+- accepts hook events from Claude Code
+- exposes channels for inter-agent messages
+
+## Transport model
+
+- HTTP for CRUD, metadata, and snapshots
+- WebSocket for live terminal IO
+- file-backed state for persistence
+
+## Security defaults
+
+- binds to `127.0.0.1` by default
+- enforces loopback `Host` and `Origin` checks by default
+- remote access must be enabled explicitly with `OCTOGENT_ALLOW_REMOTE_ACCESS=1`
+
+## Persistence model
+
+- project-local scaffold lives under `.octogent/`
+- runtime state lives under `~/.octogent/projects/<project-id>/state/`
+- transcript events persist independently from PTY scrollback
+- PTY sessions do not survive API restarts
+
+## Main API groups
+
+- terminals and snapshots
+- deck tentacles and todo operations
+- prompts
+- channels
+- code intel
+- hook ingestion
+- usage and telemetry
+- monitor
+- conversations
+
+For the exact endpoints, see [API reference](../reference/api.md).

package/apps/octogent/docs/concepts/tentacles.md

@@ -0,0 +1,85 @@
+# Tentacles
+
+Tentacles are the core abstraction in Octogent.
+
+## Definition
+
+A tentacle is a folder under `.octogent/tentacles/<tentacle-id>/` that stores agent-readable markdown files.
+
+The minimum useful files are:
+
+- `CONTEXT.md`
+- `todo.md`
+
+Additional markdown files are allowed and are surfaced as tentacle vault files in the app.
+
+## What a tentacle is for
+
+Use a tentacle when you want a durable context layer for one slice of the codebase or one track of work.
+
+Examples:
+
+- API runtime
+- frontend shell
+- prompt system
+- monitor integration
+- release work
+
+## What goes in `CONTEXT.md`
+
+`CONTEXT.md` should explain:
+
+- what this area owns
+- the important files or directories
+- what already exists
+- constraints and edge cases
+- what not to break
+- any Claude Code skills that are especially useful for this tentacle, when relevant
+
+The first heading and first non-empty paragraph are used by the runtime as the display name and description.
+
+When a tentacle has suggested Claude Code skills, Octogent appends a managed block at the bottom of `CONTEXT.md`:
+
+```md
+<!-- octogent:suggested-skills:start -->
+## Suggested Skills
+
+You can use these skills if you need to.
+
+- `skill-name`
+<!-- octogent:suggested-skills:end -->
+```
+
+## What goes in `todo.md`
+
+`todo.md` should contain markdown checkbox items:
+
+```md
+# Todo
+
+- [ ] add request validation for monitor config
+- [ ] cover the invalid payload case in tests
+- [x] wire the route into the request handler
+```
+
+The runtime parses checkbox lines and computes progress.
+
+## Tentacles and delegation
+
+The point of a tentacle is not only documentation. It is operational context.
+
+A worker attached to a tentacle can:
+
+- read local notes first
+- stay scoped to that area
+- use the todo list as a work queue
+- hand work to child agents without rebuilding context from scratch
+
+## Tentacles and worktrees
+
+Tentacles are not the same thing as worktrees.
+
+- a tentacle is a context folder
+- a worktree is an isolated git checkout for a terminal
+
+You can use a tentacle with shared workspace terminals or worktree terminals.

package/apps/octogent/docs/getting-started/installation.md

@@ -0,0 +1,54 @@
+# Installation
+
+Octogent is a local Node.js project with a local API and web UI.
+
+## Requirements
+
+- Node.js `22+`
+- `claude` for the supported workflow
+- `git` for worktree terminals
+- `gh` for GitHub pull request features
+- `curl` for the current Claude hook callback flow
+
+The current docs are Claude Code-first. Some provider plumbing exists in the codebase, but it is not the supported story yet.
+
+## Local development install
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Local global CLI install from a clone
+
+```bash
+pnpm install
+pnpm build
+npm install -g .
+```
+
+## npm registry install
+
+Octogent is not published to the npm registry yet, so `npm install -g octogent` will fail with `404`.
+
+## First run behavior
+
+Running `octogent` inside a project directory will:
+
+- create `.octogent/` if it does not exist
+- add `.octogent` to `.gitignore` or create `.gitignore` when it is missing
+- write a stable project ID to `.octogent/project.json`
+- register the project under `~/.octogent/projects.json`
+- move runtime state to `~/.octogent/projects/<project-id>/state/`
+- choose an open local API port starting at `8787`
+- open the browser unless `OCTOGENT_NO_OPEN=1`
+- show a Deck setup card until the first tentacle is created
+
+## Startup rules
+
+- startup fails if neither `claude` nor another supported provider binary is available
+- startup warns when optional integrations like `git`, `gh`, or `curl` are missing
+
+## Next step
+
+- [Quickstart](quickstart.md)

package/apps/octogent/docs/getting-started/quickstart.md

@@ -0,0 +1,79 @@
+# Quickstart
+
+This is the shortest useful path through the project.
+
+## 1. Start the app
+
+For local development:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+For a local global CLI install from a clone:
+
+```bash
+pnpm install
+pnpm build
+npm install -g .
+octogent
+```
+
+Octogent is not published to npm yet, so `npm install -g octogent` is not currently a valid quick start path.
+
+On a fresh workspace, Octogent opens the Deck setup flow first. The setup card verifies the
+workspace files, `.gitignore`, and local prerequisites before you create tentacles.
+
+## 2. Create or inspect a tentacle
+
+If the app is already running, you can create a tentacle from the CLI:
+
+```bash
+octogent tentacle create api-backend --description "API runtime and request handling"
+```
+
+Or use the Deck view in the UI.
+
+Each tentacle becomes a folder under `.octogent/tentacles/<tentacle-id>/`.
+
+## 3. Let the agent build the local context
+
+The tentacle files are where the job keeps its local context:
+
+- `CONTEXT.md` for the local model of that area
+- `todo.md` for concrete tasks
+- extra markdown files for notes, architecture, handoff, or examples
+
+You do not need to treat these as manual setup that the developer always writes by hand. One of the points of Octogent is that **Claude Code** can help create, update, and maintain these files from inside the app as the work becomes clearer.
+
+## 4. Create a terminal
+
+```bash
+octogent terminal create --name "API worker" --tentacle-id api-backend
+```
+
+Use `--workspace-mode worktree` if you want an isolated git worktree.
+
+## 5. Delegate from todo items
+
+The runtime can parse incomplete items in `todo.md` and use them as inputs when spawning child agents from the Deck swarm flow. That means one item can become one worker, or a larger list can become a swarm.
+
+## 6. Send a message
+
+```bash
+octogent channel send terminal-2 "Need review on the request parser changes"
+```
+
+## What to verify
+
+- the tentacle folder exists
+- the terminal appears in the UI
+- `CONTEXT.md` and `todo.md` exist for that tentacle
+- todo progress is visible
+- messages show up in the target terminal channel
+
+## Next reading
+
+- [Mental Model](../concepts/mental-model.md)
+- [Tentacles](../concepts/tentacles.md)

package/apps/octogent/docs/guides/inter-agent-messaging.md

@@ -0,0 +1,43 @@
+# Inter-Agent Messaging
+
+Octogent has a simple local channel system for messages between terminals.
+
+## What it is for
+
+Use channel messages for short coordination:
+
+- ask for review
+- report completion
+- hand off a finding
+- point another agent to a file or risk
+
+It is not a replacement for proper context files.
+
+## CLI usage
+
+Send a message:
+
+```bash
+octogent channel send <terminal-id> "Need review on the parser change"
+```
+
+List messages:
+
+```bash
+octogent channel list <terminal-id>
+```
+
+## API usage
+
+- `POST /api/channels/:terminalId/messages`
+- `GET /api/channels/:terminalId/messages`
+
+## Current behavior
+
+- messages are stored in memory
+- messages do not persist across API restarts
+- delivery state is tracked by the API
+
+## Practical rule
+
+If a message needs to survive, write it into the tentacle files. Use the channel for short-lived coordination only.

package/apps/octogent/docs/guides/orchestrating-child-agents.md

@@ -0,0 +1,49 @@
+# Orchestrating Child Agents
+
+Octogent uses child terminals to split work into parallel streams.
+
+## Current model
+
+- a parent terminal can exist as the main coordinator
+- child terminals can be created with a parent terminal ID
+- the Deck swarm flow can create one worker per incomplete todo item
+- workers can run in shared mode or worktree mode
+
+## When to use child agents
+
+Use child agents when:
+
+- tasks are independent enough to run in parallel
+- the parent can define clean scopes
+- each task fits one tentacle or one todo item
+
+Do not use them when the work is too entangled and the agents will overwrite each other.
+
+## Recommended workflow
+
+1. create or pick a tentacle
+2. write or refine `CONTEXT.md`
+3. break the work into checkbox items in `todo.md`
+4. spawn worker terminals from those items
+5. review results in the parent terminal
+6. use channel messages when workers need to coordinate
+
+## Shared vs worktree
+
+Use `shared` when:
+
+- the tasks are read-heavy
+- the changes are small
+- you want fast setup
+
+Use `worktree` when:
+
+- the tasks touch overlapping files
+- you want clean git isolation
+- you expect larger code edits
+
+## Limits
+
+- PTY sessions do not survive API restarts
+- channel messages are in-memory only
+- delegation quality depends on the quality of `CONTEXT.md` and `todo.md`

package/apps/octogent/docs/guides/working-with-todos.md

@@ -0,0 +1,56 @@
+# Working With Todos
+
+Todos are the operational center of a tentacle.
+
+## Format
+
+Use markdown checkboxes in `todo.md`.
+
+```md
+# Todo
+
+- [ ] inspect websocket reconnect path
+- [ ] add regression test for idle grace handling
+- [ ] update runtime docs
+```
+
+The parser only treats checkbox lines as todo items.
+
+## Good todo items
+
+Good todo items are:
+
+- specific
+- testable
+- narrow enough for one agent
+- written so they still make sense without extra chat history
+
+Bad todo items are vague and force the agent to rediscover the assignment.
+
+## Suggested pattern
+
+- keep one tentacle per work area
+- keep one `todo.md` per tentacle
+- write tasks at the level of a child agent assignment
+- mark items done in the file, not only in the UI
+
+## Why this matters
+
+The current runtime reads `todo.md`, shows progress in the Deck view, and uses incomplete items when launching swarm work.
+
+That means the todo file is both:
+
+- a planning tool for the developer
+- an execution source for delegation
+
+## Example
+
+```md
+# Todo
+
+- [ ] add API route for terminal rename
+- [ ] test invalid terminal ids
+- [ ] document rename flow in CLI reference
+```
+
+This gives you three clean delegation units instead of one oversized prompt.

package/apps/octogent/docs/index.md

@@ -0,0 +1,40 @@
+# Octogent Docs
+
+These docs are written for contributors and future coding agents.
+
+The short version:
+
+- Octogent is a local control surface over Claude Code
+- the main abstraction is the tentacle
+- a tentacle is a context folder with markdown files and todos
+- todos can be used as delegation units for child agents
+- the API manages terminals, transport, persistence, and coordination
+
+## Start here
+
+- [Installation](getting-started/installation.md)
+- [Quickstart](getting-started/quickstart.md)
+- [Mental Model](concepts/mental-model.md)
+
+## Concepts
+
+- [Tentacles](concepts/tentacles.md)
+- [Runtime and API](concepts/runtime-and-api.md)
+
+## Guides
+
+- [Working With Todos](guides/working-with-todos.md)
+- [Orchestrating Child Agents](guides/orchestrating-child-agents.md)
+- [Inter-Agent Messaging](guides/inter-agent-messaging.md)
+
+## Reference
+
+- [CLI](reference/cli.md)
+- [Filesystem Layout](reference/filesystem-layout.md)
+- [API](reference/api.md)
+- [Experimental Features](reference/experimental-features.md)
+- [Troubleshooting](reference/troubleshooting.md)
+
+## Contributor policy
+
+- [Contributing](../CONTRIBUTING.md)