Threebrain

 _______ _                   _               _
|__   __| |                 | |             (_)
   | |  | |__  _ __ ___  ___| |__  _ __ __ _ _ _ __
   | |  | '_ \| '__/ _ \/ _ \ '_ \| '__/ _' | | '_ \
   | |  | | | | | |  __/  __/ |_) | | | (_| | | | | |
   |_|  |_| |_|_|  \___|\___|_.__/|_|  \__,_|_|_| |_|

Threebrain is not chat over docs. It turns engineering work history into cited, permission-aware agent workflows.

Threebrain turns local engineering artifacts - tickets, PR exports, Slack decisions, ownership files, QA checklists, incident notes, and release rules - into cited context, workflow answers, handoffs, skillfiles, and an MCP runtime for coding agents.

It is a deterministic local file workflow that tells an agent what is known, where it came from, who owns it, which approvals block action, and which evidence the agent is allowed to see.

Install

Install the published package:

npm install -g threebrain-ai
threebrain

For quick no-install use:

npx threebrain-ai

Package identity:

npm package: threebrain-ai
CLI command: threebrain

Threebrain requires Node.js 20 or newer.

If npm install -g threebrain-ai fails with EACCES, your local npm global directory may be root-owned. Use npx threebrain-ai for a quick run, or configure a user-owned npm prefix for repeated global use. The troubleshooting guide has the exact commands.

First Run

Create a local Threebrain workspace:

mkdir threebrain-workspace
cd threebrain-workspace
threebrain init
threebrain doctor

Copy and edit templates:

cp .threebrain/templates/jira-ticket.md .threebrain/exports/jira/PROJECT-123.md
cp .threebrain/templates/github-pr.json .threebrain/exports/github/PR-1234.json
cp .threebrain/templates/slack-thread.md .threebrain/exports/slack/PROJECT-123-decision-thread.md
cp .threebrain/templates/ownership-file.yaml .threebrain/exports/ownership/example-service.yaml
cp .threebrain/templates/qa-checklist.yaml .threebrain/exports/qa/PROJECT-123-checklist.yaml
cp .threebrain/templates/release-rule.yaml .threebrain/exports/release/PROJECT-123-rules.yaml

Build the local brain:

threebrain ingest
threebrain graph build

Ask for workflow context:

threebrain context <ticket>
threebrain query "<text>"

Connect Codex through MCP:

threebrain install --platform codex

The setup command prints snippets and instructions. It does not edit Codex config files.

For the full real-workspace flow, see HOW_TO_USE.md.

5-Minute Local Walkthrough

For maintainers and reviewers, the repo includes a deterministic smoke walkthrough:

npm run walkthrough

The walkthrough generates clearly labeled synthetic local exports under ignored threebrain-out/, then runs init, ingest, graph build, skill compilation, context, handoff, query, and trust checks. It is a repeatable terminal walkthrough, not the product's data model or a hidden default fixture.

What You Get

Threebrain writes deterministic local outputs under threebrain-out/ unless your workspace config says otherwise:

threebrain-out/
  artifacts.json
  ingest-manifest.json
  work-graph.json
  context-PROJECT-123.json
  query-project-123.json
  skills/
    bug_triage.skill.md
    pr_review.skill.md
    release_qa.skill.md
    incident_response.skill.md
    engineering_handoff.skill.md

Generated outputs include:

• cited claims with source markers and evidence refs
• rendered citation details with source path, locator, and snippet when available
• permission-filtered context for the requested audience
• approval blockers for high-sensitivity release or deploy actions
• trust reports with warnings and blocking errors
• MCP tool responses for coding agents

Why Agents Use It

Agents are good at editing code. They are weaker at knowing company-specific operating context:

• which service owns this ticket
• which prior incident matters
• which Slack decision changed the implementation path
• which PR touched the risky files
• which QA checklist must run
• which release approval blocks the work
• which evidence is visible to the current audience

Threebrain gives agents that context as structured, cited, permission-aware workflow data.

Supported Inputs

Threebrain currently ingests local Markdown, JSON, and YAML files from configured workspace roots.

| Local input | Current support | Citation locators | | --- | --- | --- | | Markdown .md, .markdown | Jira ticket exports, Slack thread exports, Confluence-style docs, incident docs, and schema-shaped Markdown artifacts. | Section and line-range locators with quote snippets. | | JSON .json | GitHub PR exports and schema-shaped JSON artifacts. | JSON pointer locators with value snippets for supported fields. | | YAML .yaml, .yml | Ownership files, QA checklists, release rules, permission manifests, and schema-shaped YAML artifacts. | YAML path locators with value snippets for supported fields. |

Initialized workspaces include Jira, GitHub, Slack, Confluence-style doc, incident, QA, ownership, and release-rule templates. Full format details live in docs/artifact-format-reference.md.

Supported source types:

jira, github, slack, confluence, incident, qa, ownership, release, permission, local_file

Workspace Config

threebrain init creates:

.threebrain/config.json
.threebrain/exports/jira/.gitkeep
.threebrain/exports/github/.gitkeep
.threebrain/exports/slack/.gitkeep
.threebrain/exports/confluence/.gitkeep
.threebrain/exports/incident/.gitkeep
.threebrain/exports/qa/.gitkeep
.threebrain/exports/ownership/.gitkeep
.threebrain/exports/release/.gitkeep
.threebrain/templates/jira-ticket.md
.threebrain/templates/github-pr.json
.threebrain/templates/slack-thread.md
.threebrain/templates/confluence-doc.md
.threebrain/templates/incident-postmortem.md
.threebrain/templates/qa-checklist.yaml
.threebrain/templates/ownership-file.yaml
.threebrain/templates/release-rule.yaml
.threebrain/README.md

.threebrain/config.json uses schema threebrain.config.v1.

Important defaults:

• paths.exports: .threebrain/exports
• paths.templates: .threebrain/templates
• paths.output: threebrain-out
• defaults.deterministic: true
• defaults.llmEnrichment: false
• defaults.networkAccess: false

Configured project paths must stay inside the workspace. Absolute paths and .. parent-directory segments are rejected. Threebrain does not follow symlinks inside configured source roots; skipped symlinks are recorded in ingest-manifest.json, and threebrain doctor reports boundary issues before ingest.

Full config reference: docs/config-reference.md.

Commands

| Command | What it does | | --- | --- | | threebrain | Prints the local CLI welcome and detected workspace state. | | threebrain init | Scaffolds a local .threebrain/ workspace. | | threebrain doctor | Validates Node, config, workspace boundaries, templates, source roots, output path, and generated-output ignore coverage. | | threebrain ingest | Normalizes configured local Markdown, JSON, and YAML artifacts into artifacts.json. | | threebrain ingest --strict | Fails when skipped files are not explicitly excluded. | | threebrain graph build | Builds the typed work graph from ingested artifacts. | | threebrain context <ticket> | Generates a cited ticket context pack from graph evidence visible to the requested audience. | | threebrain handoff --owner <name> | Generates a cited owner handoff from graph evidence visible to the requested audience. | | threebrain query "<text>" --format text | Answers a workflow question with cited results and workflow sections. | | threebrain query "<text>" --format json | Emits the same query result as deterministic JSON. | | threebrain compile-skills | Generates cited local skillfiles plus a manifest from the work graph. | | threebrain citations <output> | Renders readable citation details from a generated Threebrain JSON file. | | threebrain install --platform <platform> | Prints setup snippets for codex, claude, cursor, or mcp. | | threebrain serve | Starts the Threebrain MCP stdio server against local graph data. |

Outside an initialized workspace, generated-output commands require explicit local paths such as --workspace, --out, --artifacts, or --graph.

Agent Runtime

threebrain serve exposes a local MCP stdio server over deterministic outputs.

Current tools:

threebrain.search
threebrain.get_context_pack
threebrain.get_skillfile
threebrain.graph_query
threebrain.generate_handoff

Current setup commands:

| Platform | Command | Behavior | | --- | --- | --- | | Codex | threebrain install --platform codex | Prints a codex mcp add command, a Codex TOML snippet, and optional repo-scoped skill instructions. | | Claude | threebrain install --platform claude | Prints Claude Code and Claude-compatible MCP snippets. | | Cursor | threebrain install --platform cursor | Prints Cursor-compatible mcp.json for stdio MCP. | | Generic MCP | threebrain install --platform mcp | Prints a generic MCP server JSON snippet. |

Tool arguments are validated strictly. Unknown fields and invalid graph types return explicit MCP validation errors instead of silent empty results.

Trust Model

Threebrain is evidence-first:

• Generated claims must cite work-graph evidence.
• Missing or permission-filtered evidence is reported as diagnostics or coverage notes, not proof of absence.
• Skillfile advice without semantically relevant evidence is marked as generic workflow guidance instead of citing unrelated artifacts.
• Output permissions are at least as restrictive as cited source artifacts.
• Restricted citations, citation details, trust findings, metadata, graph-derived text, MCP tools, and MCP resources are filtered by audience.
• Trust errors block generation before outputs are written. No trust override is implemented.
• Trust warnings remain visible in generated outputs.
• High-sensitivity release/deploy requirements become cited approvalBlockers with action: "do_not_proceed" and status: "blocked".

More detail: docs/accuracy.md.

Package Contract

threebrain-ai exposes one CLI and one minimal ESM API:

• CLI: threebrain
• optional CLI alias: threebrain-ai
• JS import: import { createCli, initializeWorkspace, runDoctor } from "threebrain-ai"
• types: dist/index.d.ts through package types and exports
• packaged agent skillpack: skills/threebrain/SKILL.md
• license: Apache-2.0

Packed releases include built runtime JavaScript, declaration files, README, license, package metadata, HOW_TO_USE.md, selected public docs, and the Threebrain agent skillpack. They intentionally exclude repo sources, tests, internal fixtures, scripts, generated threebrain-out/ outputs, source maps, declaration maps, and TypeScript build metadata.

Current Boundaries

Threebrain is local-first. These are intentional current boundaries:

• There is no hosted backend.
• Remote Jira, GitHub, Slack, Confluence, and other API connectors are not implemented.
• API keys, OAuth tokens, webhooks, and default network calls are not configured.
• Default LLM dependency is not required.
• Permission filtering is local artifact-level filtering, not production auth/RBAC or hosted tenant isolation.
• Search is deterministic artifact and graph matching, not semantic or vector search.
• Setup commands print client snippets; they do not mutate client config files.
• Generated outputs come from deterministic local ingestion and graph construction.

From Source

For repo development and release review:

npm install
npm run build
npm run typecheck
npm test
npm run smoke:install

Current local gate:

npm run ci

Before committing, confirm generated outputs remain ignored:

git check-ignore -v \
  threebrain-out/artifacts.json \
  threebrain-out/ingest-manifest.json \
  threebrain-out/work-graph.json \
  threebrain-out/context-PROJECT-123.json \
  threebrain-out/query-project-123.json \
  threebrain-out/skills/bug_triage.skill.md

Docs

• Architecture
• Config reference
• Artifact format reference
• Accuracy, permissions, and trust
• Troubleshooting
• Security
• Contributing