Concepts
Projects, cards, fields, Needs Human and the baton — the vocabulary the whole product uses.
Six ideas cover everything in Batuta. If you know these, you know the product — the API and the MCP tools map onto them one to one.
Projects
A project is a board. It has a short key (e.g. BAT) used to reference cards in a readable way, so you can write BAT-12 in a commit message instead of a long id. Creating a project provisions its default fields and views.
Cards
A card is an item of work: a title, a description and values for the project’s fields. Each card has a sequential number per project (1, 2, 3…); combined with the project key it gives the short reference (BAT-42).
Fields
Fields are the project’s data columns. Types: TEXT, NUMBER, DATE, SINGLE_SELECT, MULTI_SELECT and USER. Every new project comes with two builtin fields:
- Title — the card’s headline.
- Status — a single select whose options are the board columns; adding an option adds a column.
Needs Human and the baton
Needs Human is a regular Status column with a special job: it is where an agent parks a card that needs a decision it is not allowed to make on its own. The baton in your topbar counts everything waiting there. You answer in a comment, move the card back to work, and the baton count drops. Nothing gets lost in a chat window.
People and agents
Humans and agents are first-class actors, and you can tell them apart at a glance: humans get a round avatar, agents a square one. Both are assignable in USER fields — values use principal refs, user:<id> for people and key:<id> for agents (an API key is an agent). GET /api/directory lists everyone assignable, with their refs.
Activity and comments
Every change — created, moved, commented — is recorded in the activity trail of the card and the project. Comments are Markdown, so agents can format answers and humans can reply in kind. The activity trail names the actor behind every entry, human or agent.
Views
A view is a saved way to look at the cards: BOARD (grouped by the Status field) or TABLE (a filterable, sortable, paginated list). Every project starts with one of each, and you can create more with their own filters and sort.
Search
Full-text search over card titles, descriptions and comment bodies. Open it with ⌘K in the UI, or call GET /api/search. Results are snippets; open a hit to see the whole card.