How it fits together

Lucitra runs agent teams on your own machine. A team is a folder of plain files. A daemon reads it, starts each agent on a runtime you already use, and keeps a record of everything the agents do.

your team repo              your machine
──────────────              ─────────────────────────────────────
COMPANY.md                  daemon ── store (~/.lucitra)
agents/*/AGENTS.md  ──────▶   │        every step of every run
agents/*/access.yaml          │
policies/*.md                 ├── runtime: Claude Code, goose, Codex
projects/*/TASK.md            │     one agent run per git worktree
                              │
                              ├── integrations: GitHub, Alpaca, …
                              │     called on your credentials
                              │
                              └── the gate: push, deploy, orders
                                    waits where a policy says so

Teams and agents

A team is a package: a COMPANY.md, one AGENTS.md per agent, and the files that say what each agent may do. It lives in a folder, usually a git repository you own. See Writing a team package.

An agent is one role on the team: a name, a title, who it reports to, and instructions. The org chart is the permission. A lead may hand work to the agents that report to it, and to any agent it lists under mayDelegateTo, and to no one else.

The first run gives you a default team, so you can start a task before writing a package.

The daemon and the store

The daemon holds every running task and the store, an embedded Postgres under ~/.lucitra. It keeps running after you close the shell, so quitting never stops work. The shell, the app and another agent over MCP all talk to the same daemon.

Tasks and worktrees

A task is one piece of work given to one agent. It runs in its own git worktree under ~/.lucitra/worktrees, never in your checkout, and ends in a branch. A lead can split its task and delegate the parts to its reports, which run the same way.

Runtimes

A runtime is the agent CLI that does the work: Claude Code, goose or Codex, on your own subscription or key. Each agent can run on a different one. See Runtimes.

Policies and the gate

A team's policies/*.md list what is gated and what is autonomous. Anything gated waits for you in the Inbox, or at lucitra approve. Everything else runs on its own. A finished task pushes its branch and opens a pull request unless the team gates push, and a person always merges. See Run a team.

Integrations

An integration gives agents tools for an outside service: GitHub, a brokerage, market data, research, notifications. The daemon makes every call on your credentials; no agent holds a key. An agent can use a tool only where its access.yaml allows it. See Integrations.

Project memory

What the team learns about a repository is kept as markdown in that repository, under .lucitra/. Agents propose changes to it, and they arrive as a pull request a person merges. See Project memory.

Schedules and budgets

A TASK.md with a schedule: line runs on its own once you switch it on. A budget caps the tokens a team or one agent may use in a day, week or month.

The record

Every step of every run is kept: each tool call, what it returned, what the agent said, and each decision you made at the gate. lucitra run-events <task> prints it, and the app shows it live on the run's page.