@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/docs/reference/api.md

@@ -0,0 +1,103 @@
+# API Reference
+
+Octogent exposes a local HTTP and WebSocket API.
+
+## Terminals
+
+- `GET /api/terminal-snapshots` - returns the current terminal list and snapshot state for the UI
+- `POST /api/terminals` - creates a new terminal session
+- `PATCH /api/terminals/:terminalId` - updates terminal metadata such as the display name
+- `DELETE /api/terminals/:terminalId` - removes a terminal and closes its active session
+- `WS /api/terminals/:terminalId/ws` - streams live terminal IO over WebSocket
+
+## Git and worktrees
+
+- `GET /api/tentacles/:tentacleId/git/status` - reads git status for a worktree-backed tentacle
+- `POST /api/tentacles/:tentacleId/git/commit` - creates a commit from the tentacle worktree
+- `POST /api/tentacles/:tentacleId/git/push` - pushes the tentacle branch
+- `POST /api/tentacles/:tentacleId/git/sync` - syncs the tentacle worktree with its base branch
+- `GET /api/tentacles/:tentacleId/git/pr` - reads pull request information for the tentacle branch
+- `POST /api/tentacles/:tentacleId/git/pr/merge` - merges the tentacle pull request
+
+## Deck and tentacles
+
+- `GET /api/deck/skills` - lists available Claude Code skills discovered from project-local `.claude/skills/<skill>/SKILL.md` entries
+- `GET /api/deck/tentacles` - lists tentacles with metadata, vault files, and todo progress
+- `POST /api/deck/tentacles` - creates a new tentacle
+- `DELETE /api/deck/tentacles/:tentacleId` - deletes a tentacle and its stored files
+- `PATCH /api/deck/tentacles/:tentacleId/skills` - updates the tentacle's suggested Claude Code skills and rewrites the managed block in `CONTEXT.md`
+- `POST /api/deck/tentacles/:tentacleId/todo` - adds a todo item to `todo.md`
+- `PATCH /api/deck/tentacles/:tentacleId/todo/toggle` - marks a todo item done or undone
+- `PATCH /api/deck/tentacles/:tentacleId/todo/edit` - edits the text of a todo item
+- `POST /api/deck/tentacles/:tentacleId/todo/delete` - deletes a todo item
+- `GET /api/deck/tentacles/:tentacleId/files/:filename` - reads one markdown file from the tentacle vault
+- `POST /api/deck/tentacles/:tentacleId/swarm` - spawns worker terminals from incomplete todo items
+
+## Prompts
+
+- `GET /api/prompts` - lists available prompt templates
+- `POST /api/prompts` - creates a user prompt
+- `GET /api/prompts/:promptId` - reads one prompt
+- `PUT /api/prompts/:promptId` - updates one prompt
+- `DELETE /api/prompts/:promptId` - deletes one prompt
+
+## Channels
+
+- `GET /api/channels/:terminalId/messages` - lists messages for one terminal channel
+- `POST /api/channels/:terminalId/messages` - sends a message to one terminal channel
+
+## Code intel
+
+- `POST /api/code-intel/events` - records one code-intel event
+- `GET /api/code-intel/events` - returns the stored code-intel event log
+
+## Hooks
+
+- `POST /api/hooks/:hookName` - ingests lifecycle events coming from Claude Code hooks
+
+Current hook names:
+
+- `session-start`
+- `user-prompt-submit`
+- `pre-tool-use`
+- `notification`
+- `stop`
+
+## Usage and telemetry
+
+- `GET /api/codex/usage` - returns Codex usage data when available
+- `GET /api/claude/usage` - returns Claude usage data when available
+- `GET /api/github/summary` - returns GitHub summary and repo telemetry data
+- `GET /api/analytics/usage-heatmap?scope=all|project` - returns heatmap data from Claude session history
+
+## UI state
+
+- `GET /api/ui-state` - reads the persisted UI state for the current project
+- `PATCH /api/ui-state` - updates the persisted UI state
+
+## Workspace setup
+
+- `GET /api/setup` - reads the verified first-run setup status for the current workspace
+- `POST /api/setup/steps/:stepId` - runs one setup step and returns the refreshed setup snapshot
+
+## Monitor
+
+- `GET /api/monitor/config` - reads monitor configuration
+- `PATCH /api/monitor/config` - updates monitor configuration
+- `GET /api/monitor/feed` - returns the current monitor feed snapshot
+- `POST /api/monitor/refresh` - forces a monitor refresh
+
+## Conversations
+
+- `GET /api/conversations` - lists stored conversations
+- `DELETE /api/conversations` - deletes all stored conversations
+- `GET /api/conversations/search?q=...` - searches conversations by text
+- `GET /api/conversations/:sessionId` - reads one conversation in full
+- `GET /api/conversations/:sessionId/export?format=json|md` - exports one conversation as JSON or Markdown
+
+## Request limits and defaults
+
+- JSON request bodies are capped at `1 MiB`
+- invalid JSON returns `400`
+- unsupported methods return `405`
+- the server binds to loopback by default

package/apps/octogent/docs/reference/cli.md

@@ -0,0 +1,71 @@
+# CLI Reference
+
+## Start the dashboard
+
+```bash
+octogent
+```
+
+Starts the local API for the current project and opens the UI when bundled web assets are present.
+
+If the current directory has not been initialized yet, `octogent` also creates or updates the local `.octogent/` scaffold automatically on first run.
+
+## Initialize a project
+
+```bash
+octogent init [project-name]
+```
+
+Creates or updates the `.octogent/` scaffold in the current directory without starting the dashboard.
+
+Use this when you want to initialize the project explicitly or set the project display name ahead of time. In normal use, running `octogent` inside the codebase is enough to initialize and start the app.
+
+## List registered projects
+
+```bash
+octogent projects
+```
+
+## Create a tentacle
+
+```bash
+octogent tentacle create <name> --description "API runtime and routes"
+```
+
+Octogent must already be running for this command.
+
+## List tentacles
+
+```bash
+octogent tentacle list
+```
+
+## Create a terminal
+
+```bash
+octogent terminal create [options]
+```
+
+Options:
+
+- `--name`, `-n`: terminal display name
+- `--workspace-mode`, `-w`: `shared` or `worktree`
+- `--initial-prompt`, `-p`: raw initial prompt text
+- `--terminal-id`: explicit terminal ID
+- `--tentacle-id`: existing tentacle ID to attach to
+- `--worktree-id`: explicit worktree ID
+- `--parent-terminal-id`: parent terminal ID for child terminals
+- `--prompt-template`: prompt template name
+- `--prompt-variables`: JSON object of prompt template variables
+
+## Send a message
+
+```bash
+octogent channel send <terminal-id> "message"
+```
+
+## List messages
+
+```bash
+octogent channel list <terminal-id>
+```

package/apps/octogent/docs/reference/experimental-features.md

@@ -0,0 +1,28 @@
+# Experimental Features
+
+These features exist in the repo, but they are not the center of the current project story.
+
+## Secondary surfaces
+
+- monitor
+- GitHub summary and metrics
+- user and token usage views
+- prompt library UI
+- code intel
+- conversations
+
+## Why they are secondary
+
+The main project claim is about:
+
+- tentacles
+- todos
+- Claude Code terminals
+- child-agent orchestration
+- inter-agent messaging
+
+Everything else should be treated as supporting or experimental unless the docs say otherwise.
+
+## Documentation rule
+
+Do not let these features dominate the landing page or the core concepts pages.

package/apps/octogent/docs/reference/filesystem-layout.md

@@ -0,0 +1,62 @@
+# Filesystem Layout
+
+## Project-local files
+
+`.octogent/` is created in the workspace.
+
+Main paths:
+
+- `.octogent/project.json`
+- `.octogent/tentacles/`
+- `.octogent/worktrees/`
+
+Tentacle example:
+
+```text
+.octogent/
+  tentacles/
+    api-backend/
+      CONTEXT.md
+      todo.md
+      routes.md
+```
+
+`CONTEXT.md` may end with a managed `Suggested Skills` block when the operator or planner attaches Claude Code skills to that tentacle.
+
+Project-local Claude Code skills, when present, live under:
+
+```text
+.claude/
+  skills/
+    some-skill/
+      SKILL.md
+```
+
+## Global state
+
+Per-project runtime state is stored under:
+
+```text
+~/.octogent/projects/<project-id>/state/
+```
+
+Notable files:
+
+- `tentacles.json`
+- `deck.json`
+- `transcripts/<sessionId>.jsonl`
+- `monitor-config.json`
+- `monitor-cache.json`
+- `code-intel.jsonl`
+
+## Prompt storage
+
+- core prompts are synced from `prompts/`
+- synced copies live in `.octogent/prompts/core/`
+- user prompts live in `.octogent/prompts/`
+
+## Practical rule
+
+If something is agent-facing context, keep it in the tentacle folder.
+
+If something is runtime-owned state, expect it under the global project state directory.

package/apps/octogent/docs/reference/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+## `pnpm test` fails because of browser APIs
+
+Make sure the workspace dependencies are installed from the repo root:
+
+```bash
+pnpm install
+```
+
+## Package resolution is broken
+
+Run install from the repository root, not from a subpackage.
+
+## Node version is too old
+
+Use Node.js `22+`.
+
+## Terminal startup fails
+
+Check that your shell environment is available and executable.
+
+## Worktree terminal creation fails
+
+Verify:
+
+- `git --version` works
+- the workspace is a git repository
+- the current user can create worktrees in `.octogent/worktrees/`
+
+## GitHub summary is unavailable
+
+Verify:
+
+```bash
+gh auth status
+```
+
+## Monitor refresh fails
+
+Verify your X bearer token and API access.
+
+## Messages disappear after restart
+
+That is expected. Channel messages are in-memory only and do not persist across API restarts.
+
+## A terminal survived reload but not server restart
+
+That is also expected. PTY sessions can survive a reconnect window, but they do not survive an API restart.

package/apps/octogent/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "octogent",
+  "version": "0.1.0",
+  "description": "Web-first command surface for running multiple coding agents in parallel",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@10.4.1",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "octogent": "./bin/octogent"
+  },
+  "files": ["bin", "dist", "README.md"],
+  "scripts": {
+    "start": "pnpm dev",
+    "dev": "node scripts/dev.mjs",
+    "build": "pnpm --filter @octogent/web build && pnpm --filter @octogent/web exec vite build --config vite.api.bundle.config.mts && node scripts/build-package.mjs",
+    "smoke:public-install": "node scripts/smoke-public-install.mjs",
+    "test": "pnpm -r test",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.13.10",
+    "knip": "^6.3.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.7"
+  }
+}

package/apps/octogent/packages/core/AGENTS.md

@@ -0,0 +1,31 @@
+# Core Guidelines
+
+## Ownership
+- `packages/core` holds framework-agnostic domain types, application logic, ports, and small adapters that stay independent of app runtimes.
+- This package is the shared contract between `apps/api` and `apps/web`.
+
+## Relevant Docs
+- `docs/concepts/mental-model.md`
+- `docs/concepts/tentacles.md`
+- `docs/concepts/runtime-and-api.md`
+- `docs/reference/api.md`
+- `docs/reference/filesystem-layout.md`
+- Read these when changing shared domain terminology, runtime contracts, persistence-facing types, or cross-app behavior.
+
+## Boundaries
+- No React, HTTP server, PTY, process execution, filesystem persistence, or browser-specific behavior here.
+- Prefer pure functions and explicit interfaces over runtime-coupled helpers.
+- If logic needs app infrastructure to run, keep the interface in core and the implementation in the owning app.
+
+## Design
+- Keep the ports-and-adapters split clear:
+  - `domain/` for core types and concepts
+  - `application/` for use-case logic
+  - `ports/` for system boundaries
+  - lightweight adapters only when they stay framework-agnostic
+- Avoid leaking app-specific naming or transport details into shared types unless that detail is truly part of the domain contract.
+
+## Change Discipline
+- Be cautious with exported types and functions. Changes here usually affect both apps.
+- When modifying shared contracts, update the dependent call sites and add tests that pin the behavior from the core package outward.
+- Prefer additive changes and normalization helpers over breaking contract churn.

package/apps/octogent/packages/core/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@octogent/core",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/apps/octogent/packages/core/src/adapters/InMemoryTerminalSnapshotReader.ts

@@ -0,0 +1,10 @@
+import type { TerminalSnapshot } from "../domain/terminal";
+import type { TerminalSnapshotReader } from "../ports/TerminalSnapshotReader";
+
+export class InMemoryTerminalSnapshotReader implements TerminalSnapshotReader {
+  constructor(private readonly snapshots: TerminalSnapshot[]) {}
+
+  async listTerminalSnapshots(): Promise<TerminalSnapshot[]> {
+    return this.snapshots;
+  }
+}

package/apps/octogent/packages/core/src/application/buildTerminalList.ts

@@ -0,0 +1,13 @@
+import type { TerminalSnapshotReader } from "../ports/TerminalSnapshotReader";
+
+const byCreatedAtAscending = (a: string, b: string): number =>
+  new Date(a).getTime() - new Date(b).getTime();
+
+export const buildTerminalList = async (
+  reader: TerminalSnapshotReader,
+): Promise<Awaited<ReturnType<typeof reader.listTerminalSnapshots>>> => {
+  const snapshots = await reader.listTerminalSnapshots();
+  return [...snapshots].sort((left, right) =>
+    byCreatedAtAscending(left.createdAt, right.createdAt),
+  );
+};

package/apps/octogent/packages/core/src/domain/agentRuntime.ts

@@ -0,0 +1,18 @@
+export type AgentRuntimeState =
+  | "idle"
+  | "processing"
+  | "waiting_for_permission"
+  | "waiting_for_user";
+
+export const isAgentRuntimeState = (value: unknown): value is AgentRuntimeState =>
+  value === "idle" ||
+  value === "processing" ||
+  value === "waiting_for_permission" ||
+  value === "waiting_for_user";
+
+export type TerminalAgentProvider = "codex" | "claude-code";
+
+export const TERMINAL_AGENT_PROVIDERS: TerminalAgentProvider[] = ["codex", "claude-code"];
+
+export const isTerminalAgentProvider = (value: unknown): value is TerminalAgentProvider =>
+  typeof value === "string" && TERMINAL_AGENT_PROVIDERS.includes(value as TerminalAgentProvider);

package/apps/octogent/packages/core/src/domain/channel.ts

@@ -0,0 +1,8 @@
+export type ChannelMessage = {
+  messageId: string;
+  fromTerminalId: string;
+  toTerminalId: string;
+  content: string;
+  timestamp: string;
+  delivered: boolean;
+};

package/apps/octogent/packages/core/src/domain/completionSound.ts

@@ -0,0 +1,14 @@
+export const TERMINAL_COMPLETION_SOUND_IDS = [
+  "soft-chime",
+  "retro-beep",
+  "double-beep",
+  "bell",
+  "pop",
+  "silent",
+] as const;
+
+export type TerminalCompletionSoundId = (typeof TERMINAL_COMPLETION_SOUND_IDS)[number];
+
+export const isTerminalCompletionSoundId = (value: unknown): value is TerminalCompletionSoundId =>
+  typeof value === "string" &&
+  TERMINAL_COMPLETION_SOUND_IDS.includes(value as TerminalCompletionSoundId);

package/apps/octogent/packages/core/src/domain/conversation.ts

@@ -0,0 +1,48 @@
+export type ConversationTurn = {
+  turnId: string;
+  role: "user" | "assistant";
+  content: string;
+  startedAt: string;
+  endedAt: string;
+};
+
+export type ConversationTranscriptEvent = {
+  eventId: string;
+  sessionId: string;
+  tentacleId: string;
+  timestamp: string;
+  type: "session_start" | "input_submit" | "output_chunk" | "state_change" | "session_end";
+};
+
+export type ConversationSessionSummary = {
+  sessionId: string;
+  tentacleId: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  lastEventAt: string | null;
+  eventCount: number;
+  turnCount: number;
+  userTurnCount: number;
+  assistantTurnCount: number;
+  firstUserTurnPreview: string | null;
+  lastUserTurnPreview: string | null;
+  lastAssistantTurnPreview: string | null;
+};
+
+export type ConversationSessionDetail = ConversationSessionSummary & {
+  turns: ConversationTurn[];
+  events: ConversationTranscriptEvent[];
+};
+
+export type ConversationSearchHit = {
+  sessionId: string;
+  turnId: string;
+  role: "user" | "assistant";
+  snippet: string;
+  turnStartedAt: string;
+};
+
+export type ConversationSearchResult = {
+  query: string;
+  hits: ConversationSearchHit[];
+};

package/apps/octogent/packages/core/src/domain/deck.ts

@@ -0,0 +1,33 @@
+export type DeckTentacleStatus = "idle" | "active" | "blocked" | "needs-review";
+
+export type DeckOctopusAppearance = {
+  animation: string | null;
+  /** Valid: "normal" | "happy" | "angry" | "surprised". "sleepy" is reserved for idle state — never assign on creation. */
+  expression: string | null;
+  accessory: string | null;
+  hairColor: string | null;
+};
+
+export type DeckAvailableSkill = {
+  name: string;
+  description: string;
+  source: "project" | "user";
+};
+
+export type DeckTentacleSummary = {
+  tentacleId: string;
+  displayName: string;
+  description: string;
+  status: DeckTentacleStatus;
+  color: string | null;
+  octopus: DeckOctopusAppearance;
+  scope: {
+    paths: string[];
+    tags: string[];
+  };
+  vaultFiles: string[];
+  todoTotal: number;
+  todoDone: number;
+  todoItems: { text: string; done: boolean }[];
+  suggestedSkills: string[];
+};

package/apps/octogent/packages/core/src/domain/git.ts

@@ -0,0 +1,32 @@
+import type { TentacleWorkspaceMode } from "./terminal";
+
+export type TentaclePullRequestStatus = "none" | "open" | "merged" | "closed";
+
+export type TentacleGitStatusSnapshot = {
+  tentacleId: string;
+  workspaceMode: TentacleWorkspaceMode;
+  branchName: string;
+  upstreamBranchName: string | null;
+  isDirty: boolean;
+  aheadCount: number;
+  behindCount: number;
+  insertedLineCount: number;
+  deletedLineCount: number;
+  hasConflicts: boolean;
+  changedFiles: string[];
+  defaultBaseBranchName: string | null;
+};
+
+export type TentaclePullRequestSnapshot = {
+  tentacleId: string;
+  workspaceMode: TentacleWorkspaceMode;
+  status: TentaclePullRequestStatus;
+  number: number | null;
+  url: string | null;
+  title: string | null;
+  baseRef: string | null;
+  headRef: string | null;
+  isDraft: boolean | null;
+  mergeable: "MERGEABLE" | "CONFLICTING" | "UNKNOWN" | null;
+  mergeStateStatus: string | null;
+};

package/apps/octogent/packages/core/src/domain/monitor.ts

@@ -0,0 +1,62 @@
+export type MonitorUsageSnapshot = {
+  status: "ok" | "unavailable" | "error";
+  source: "x-api" | "none";
+  fetchedAt: string;
+  message?: string | null;
+  cap?: number | null;
+  used?: number | null;
+  remaining?: number | null;
+  resetAt?: string | null;
+};
+
+export type MonitorPost = {
+  source: "x";
+  id: string;
+  text: string;
+  author: string;
+  createdAt: string;
+  likeCount: number;
+  permalink: string;
+  matchedQueryTerm: string | null;
+};
+
+export type MonitorCredentialSummary = {
+  isConfigured: boolean;
+  bearerTokenHint: string | null;
+  apiKeyHint: string | null;
+  hasApiSecret: boolean;
+  hasAccessToken: boolean;
+  hasAccessTokenSecret: boolean;
+  updatedAt: string | null;
+};
+
+export type MonitorConfigSnapshot = {
+  providerId: "x";
+  queryTerms: string[];
+  refreshPolicy: {
+    maxCacheAgeMs: number;
+    maxPosts: number;
+    searchWindowDays: 1 | 3 | 7;
+  };
+  providers: {
+    x: {
+      credentials: MonitorCredentialSummary;
+    };
+  };
+};
+
+export type MonitorFeedSnapshot = {
+  providerId: "x";
+  queryTerms: string[];
+  refreshPolicy: {
+    maxCacheAgeMs: number;
+    maxPosts: number;
+    searchWindowDays: 1 | 3 | 7;
+  };
+  lastFetchedAt: string | null;
+  staleAfter: string | null;
+  isStale: boolean;
+  lastError: string | null;
+  posts: MonitorPost[];
+  usage: MonitorUsageSnapshot | null;
+};

package/apps/octogent/packages/core/src/domain/setup.ts

@@ -0,0 +1,27 @@
+export type WorkspaceSetupStepId =
+  | "initialize-workspace"
+  | "ensure-gitignore"
+  | "check-claude"
+  | "check-git"
+  | "check-curl"
+  | "create-tentacles";
+
+export type WorkspaceSetupStep = {
+  id: WorkspaceSetupStepId;
+  title: string;
+  description: string;
+  complete: boolean;
+  required: boolean;
+  actionLabel: string | null;
+  statusText: string;
+  guidance: string | null;
+  command: string | null;
+};
+
+export type WorkspaceSetupSnapshot = {
+  isFirstRun: boolean;
+  shouldShowSetupCard: boolean;
+  hasAnyTentacles: boolean;
+  tentacleCount: number;
+  steps: WorkspaceSetupStep[];
+};