The Big Picture¶

What tatara is trying to solve¶

Software engineering teams accumulate backlog faster than they can ship. Issues pile up, minor improvements are perpetually deferred, and on-call engineers spend time on repetitive triage. Meanwhile, AI coding assistants (GitHub Copilot, Claude Code, Cursor, and the like) are good at writing code given a clear spec - but on their own they are stateless. Each session starts from scratch, forgets what was decided before, and has no awareness of the broader system.

Tatara connects the dots: it gives AI agents durable memory of your codebase, structured task tracking in Kubernetes, and a continuous feedback loop with your GitHub/GitLab workflow.

The forge metaphor¶

The name comes from the Japanese tatara iron-smelting forge: a collective, iterative process organized around a permanent substrate. That is the design intent:

• The permanent substrate is the knowledge graph (LightRAG + Neo4j). It lives in your cluster, grows as your codebase evolves, and survives across agent sessions.
• The ephemeral sessions are the Claude Code pods. They start, do a piece of work, commit it, and terminate. The next session picks up where the last one left off because the graph is still there.
• The iterative process is the issue-to-PR loop: propose, approve, implement, review, merge, repeat.

The platform in one diagram¶

Your GitHub/GitLab org
        |
        | You open an issue (no label required)
        |
        v
tatara-operator (Kubernetes)
        |
        | 1. Creates a Task CR
        | 2. Spawns a claude-code-wrapper Pod
        |
        v
Claude Code (inside the Pod)
        |
        | reads codebase memory
        | writes code
        | opens PR
        |
        v
GitHub/GitLab PR
        |
        | Human reviews, approves, merges
        |
        v
Done

The operator is the glue. It watches your SCM for events, maintains the queue, spawns and monitors agent pods, and writes results back.

What the agent actually does¶

Inside each pod, Claude Code runs as it would on your laptop - in its full interactive mode, with all its tools, skills, and the same decision-making loop. The difference is the environment:

• Instead of a human at a keyboard, a Go supervisor submits messages programmatically
• Instead of your local files, the agent works in a cloned repository mounted in /workspace
• Instead of reading docs from scratch, it queries a pre-built knowledge graph of your codebase

The agent can read files, write code, run tests, call APIs (via MCP tools), and push commits. It cannot log into arbitrary services or access secrets it was not explicitly given.

The loop runs itself, mostly¶

Reacting to human-filed issues is only one of the agent kinds tatara runs. The platform also generates and maintains its own backlog, responds to alerts, and can deploy itself:

• brainstorm proposes net-new work as fresh issues (capped per project). A bot-filed proposal will not auto-approve into implementation until a human engages with it.
• refine grooms the existing backlog - tightening, de-duplicating, and closing stale proposals - without opening or implementing anything itself.
• incident fires from Grafana alert webhooks: an alert at 3am spawns an investigation agent that gathers context and reports back for a human in the morning.
• push-CD lets tatara ship its own components: a merged change with a declared significance rides a semver release cascade all the way to a tatara-helmfile apply (walked through in From Issue to PR).

So not every unit of work starts from a human-labeled issue. What stays with humans is the scope (which repos are enrolled), approval of proposed net-new work, and the merge gate. Within those bounds the loop is largely self-driving.

What humans control¶

Tatara runs much of its own loop, but the load-bearing decisions stay with humans:

1. Which repositories are enrolled. Tatara triages every open issue in an enrolled repo via the periodic issue scan - no label is required. The optional trigger label only makes it skip triage and start implementing immediately; it is not an act/no-act switch.
2. Whether to approve net-new work the agent proposes. Brainstorm-generated proposals wait for a human before they are implemented.
3. Whether to approve the agent's triage plan, by commenting in the issue thread.
4. Whether to merge the PR, by reviewing and approving in your SCM. (Under the default afterApproval policy the operator merges on the agent's own read of the thread rather than verifying SCM review state directly; see the approval-gates reference for how to make that a hard gate with branch protection.)

The agent proposes, grooms, implements, and can even ship its own components; humans set scope and hold the merge gate. This is the design intent, not a limitation.

What makes tatara different from a CI/CD script¶

A CI/CD script runs fixed commands. Tatara runs an AI agent that reasons about your specific codebase. The agent reads your code, understands your patterns, asks clarifying questions if the spec is ambiguous, and writes code in your style.

The tradeoff is that agent behavior is probabilistic, not deterministic. The human approval gates exist precisely because of this: you review the plan before implementation, and you review the code before merge.

What could go wrong (and how tatara handles it)¶