How it works

How ContextBrain works, end to end

From the code and docs you already have, to a pull request an agent opens for you — here is the whole pipeline, then a walkthrough of one real task moving through it: issue → session → context pack → PR, watched the whole way.

The pipeline at a glance

ContextBrain sits between your code and every AI agent you use. Work flows through seven stages, each one observable:

Sources — your repositories, documents, designs, tickets, and chat feed in. See context sources for every channel.
Ingest — a full sweep on connect, then incremental updates on every webhook (commits, branches, default-branch sync), so context stays fresh without manual re-indexing.
Knowledge graph — code and docs become a queryable graph of files, symbols, and references with call / import / defines relationships. See the knowledge graph.
Retrieval — hybrid search (semantic embeddings + BM25 keyword + entity matches, fused with Reciprocal Rank Fusion) finds the right code, not just keyword matches.
Context pack— the task-specific bundle is assembled, scored for confidence and freshness, pruned to the model's token budget, and hash-signed. See context packs.
Agent — any agent (Claude, Codex, Gemini, Aider) receives the pack over MCP, in cloud or self-hosted daemon mode, and does the work.
PR — the agent opens a pull request and reports back to the issue, every step costed and audited.

The model never works blind. By the time an agent touches your code, it already has the exact files, the real schema, the team's rules, the ticket, and prior similar work — scoped to the one task in front of it.

A real task, start to finish

The clearest way to understand ContextBrain is to follow a single unit of work through the loop. Here is what actually happens when an issue is handed to an agent.

1. An issue is assigned to an agent

On the project board, a teammate assigns an issue to an agent (or a whole squad — a leader agent plus members). Issue assignment is polymorphic: a unit of work can go to a human member, an agent, or a squad. Assigning to an agent or squad — or moving the issue to in_progress, or hitting Start session, or a cron schedule firing — is what triggers the next step.

2. A session is dispatched

ContextBrain creates an agent_sessions row in queued status — the session, not the issue, is the unit that runs. Dispatch loads the agent, the project, the routed repository, the context pack, and the linked issue, then composes the prompt. User text (the task title and description) is wrapped in delimiters and treated as data, not instructions— a prompt-injection guard. The composed prompt layers agent instructions, per-agent and org-shared skills, the context-pack markdown, repo context (which repo it owns plus read-only sibling repos), and issue context. For a squad, a Squad Operating Protocol is prepended to the leader's instructions.

3. The context pack is composed

Retrieval runs for the task and the context packis assembled from multiple sources — code chunks, three-tier memory, documents, tickets, coding guidelines, the schema of record, and similar prior features. Each section is scored, the whole pack is pruned to fit the target model's window, and a hash-signed manifest is recorded on the session so you can later prove exactly what the AI saw.

4. The agent works

The session is dispatched to the runtime — cloud, or a self-hosted daemon that keeps the code inside your perimeter. Execution is not polled: ContextBrain waits for an asynchronous webhook. As the run progresses, the session timeline fills with type-grouped events, files modified, QA and security checks, and a token / cost breakdown.

5. It opens a PR and reports back

When the run reaches a terminal status, the webhook arrives — idempotent by event hash — and updates the session with the final status, the timeline, the files modified, the cost, and the PR URL and number. If the session was started from an issue, ContextBrain posts a system comment back to that issue's thread (“session completed, opened PR …”). A squad leader can also delegate to members, each delegated child capped by a turn counter so the loop can't run away.

The result: a pull request you can review, with a complete, audited record of what the agent did and the exact context it had when it did it. That is the loop ContextBrain owns — issue to PR, watched the whole way.

Where to go next

Dig into the channels at context sources, the knowledge graph that powers retrieval, the context packs agents consume, or chat with your codebase over MCP.