<!--
This file was generated by `mise run docs`. DO NOT EDIT.
Edit `doc/readme/README.md` and its linked source files instead.
-->
# Cardamom
- [Introduction](#introduction)
- [Status](#status)
- [Features](#features)
- [Installation](#installation)
- [Getting started](#getting-started)
- [Issue model](#issue-model)
- [User guide](#user-guide)
- [History](#history)
- [License](#license)
## Introduction
<div align="center">
<img src="doc/img/logo.png" width="300"/>
</div>
Cardamom is a local work tracker for your AI agents.
It carries context between tasks, agents, and processes.
It organizes work in a durable issue graph.
It lets agents (and subagents) claim tasks atomically
and coordinate with each other through a shared local store.
Use Cardamom when work needs your agent to have an attention span.
## Status
This project is currently in beta.
While we will try to avoid it, breaking changes are possible.
Use at your own risk.
## Features
- **Tasks with context**:
Cardamom models work as a graph of issues.
Parent issues contribute context to their children,
so an agent sees all the relevant context of its task.
- **Record and replay**:
Agents record decisions with Cardamom as they work.
If an agent is lost, another agent can replay the history
and end up roughly where the lost agent left off.
- **Full-text issue discovery**:
Ranked board search spans issue plans, progress, outcomes, and Log history,
with filters and excerpts that lead to focused follow-up reads.
- **Multiple sub-agents or processes**:
Cardamom supports coordination of work across
multiple sub-agents in the same process,
or multiple agents in different processes,
or a mixture of both.
- **Built-in web view**:
The built-in web view provides a live view of issue state.
- **Flexible storage and boards**:
Cardamom supports storing state on a per-user or per-repository basis.
Within a store, your work can be organized into one board (per-repository)
or multiple boards (e.g. per long-running effort).
- **Private by default**:
Cardamom does not litter your repository.
State is stored locally in a SQLite database.
You may generate [Markdown collections](doc/guide/markdown-collections.md)
to commit a report of your work, but the state itself is not shared.
- **Non-intrusive**:
Cardamom does not require you to change your entire workflow,
or use a completely different harness.
It fits into your existing workflow, usable with your current harness.
Install it as a skill, and use it to coordinate your agents.
## Installation
Install Cardamom for Claude Code, Codex, or as a standalone command.
### Claude Code
1. Add the Cardamom repository marketplace.
```bash
claude plugin marketplace add abhinav/cardamom
```
2. Install the plugin.
```bash
claude plugin install cardamom@cardamom
```
To update the plugin:
```bash
claude plugin marketplace update cardamom
claude plugin update cardamom@cardamom
```
### Codex
1. Add the Cardamom repository marketplace.
```bash
codex plugin marketplace add abhinav/cardamom
```
2. Install the plugin.
```bash
codex plugin add cardamom@cardamom
```
To update the plugin:
```bash
codex plugin marketplace upgrade cardamom
codex plugin add cardamom@cardamom
```
### Standalone command
Install the public `card` command directly to use Cardamom from your shell
or with another agent host.
- **Homebrew** or **Linuxbrew**
```bash
brew install --cask abhinav/tap/cardamom
```
- **GitHub Releases**
Pre-built binaries are available on the
[GitHub Releases](https://github.com/abhinav/cardamom/releases) page.
```bash
mkdir -p "$HOME/.local/bin"
curl -fsSL "https://github.com/abhinav/cardamom/releases/latest/download/cardamom.$(uname -s)-$(uname -m).tar.gz" |
tar -xz -C "$HOME/.local/bin" card
```
- **Install from source**
To build and install Cardamom from source, clone the repository,
set up [Mise](https://mise.jdx.dev/), and run:
```bash
mise run build
cp bin/card "$HOME/.local/bin"
```
After installing `card`,
install its embedded Cardamom skill into an agent host's parent skills
directory:
```bash
card skill install ~/.agents/skills
```
The command writes the skill to `~/.agents/skills/cardamom`.
An identical destination is left unchanged.
If the destination differs,
inspect it before passing `--force` to replace the complete directory.
## Getting started
Start Claude Code or Codex in the project you want to coordinate,
then ask the agent:
```text
Use the Cardamom skill to plan and coordinate this work.
```
Cardamom task-management commands are primarily for agents.
This example shows a hypothetical coordinator and two workers
using them in parallel.
- The coordinator initializes Cardamom and creates two independent tasks.
```bash
export CARDAMOM_ACTOR=coordinator
card init
workstream=$(card create --type workstream \
--summary "Publish the operator and reviewer procedures." \
"Publish release documentation")
card create \
--parent "$workstream" --label area:installation \
--summary "Document the supported installation paths." \
"Write the installation guide"
card create \
--parent "$workstream" --label area:release \
--summary "Record each release step and owner." \
"Write the release guide"
```
The workstream groups the two related tasks.
- Parallel workers receive the tasks,
using `--watch` to wait for available work.
```bash
card --actor worker1 --json claim --context --watch
card --actor worker2 --json claim --context --watch
```
- Each worker records progress in the task's State.
This can be used later to resume work if the worker is lost.
```bash
export CARDAMOM_ACTOR=worker1
card state set <task-id> \
"The release inputs are identified." \
--next "Add checksum publication."
```
- The worker records the task's result and releases it to the coordinator.
The coordinator accepts and closes that task.
```bash
export CARDAMOM_ACTOR=worker1
card state set <task-id> \
"The release guide is ready for acceptance." \
--next "The coordinator reviews the result."
card result set <task-id> \
"Documented the release steps and checksum publication."
card release <task-id> \
--waiting "coordinator acceptance"
export CARDAMOM_ACTOR=coordinator
card result show <task-id>
card close <task-id>
```
While the agents work,
you can browse live status in the web UI with `card web`,
or add new tasks manually with `card create` when you want to steer the work.
## Issue model
Workstreams represent larger deliverables.
They can contain tasks and nested workstreams.
Tasks are independently executable units of work.
Each issue has a short summary for its stable contract.
Details hold longer rationale, procedures, and supporting context.
Children automatically receive every ancestor summary.
Ancestor details and deeper context remain queryable when needed.
## User guide
Continue with either form of the guide:
- [One-page user guide](USER_GUIDE.md) for search, offline reading,
and broad scanning.
- [Browseable topic index](doc/guide/README.md) for concepts,
setup choices, workflow recipes, observability, coordination,
attachments, and Markdown publication.
Command syntax remains available from `card --help`
and `card <command> --help`.
The guide concentrates on decisions and workflows rather than duplicating a
command reference.
## History
The project started as a fork of [arjia-labs/clu](https://github.com/arjia-labs/clu).
Soon after starting, a different direction was required
and the original code was discarded.
Cardamom still borrows ideas from `clu`,
and we thank Roy van Kaathoven for his original work on `clu`.
## License
Cardamom is distributed under the [BSD3 license](LICENSE).