Metadata-Version: 2.1
Name: teabag
Version: 0.1.0
Summary: AI-native version control CLI for safe AI-assisted development.
Author-email: teaBag <devnull@example.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# teaBag — How to Use

teaBag is a CLI for **AI-native version control**: it keeps your main codebase safe while AI tools edit code in isolated workspaces, and it records every run (prompt, intent, and diff) so you can review, compare, and merge changes in a structured way.

The CLI command is **`tb`**.

---

## Installation

From the teaBag project root:

```bash
pip install -e .
```

This installs the `tb` command. Requires **Python 3.10+** and a **git** repository (recommended) for diff capture.

---

## Quick Start

```bash
cd /path/to/your/project

# 1. Initialize teaBag (creates .teabag/, workspaces/, .ai_history/, env_store/)
tb init

# 2. Create a workspace for an AI agent
tb spawn agent_1

# 3. Human fills prompt.json (tb spawn creates a default with _teabag section)
#    AI reads prompt.json and writes intent.json (only intent.json first)
# 4. Point your AI at workspaces/agent_1 to edit code, then record the run
tb run agent_1

# 5. List runs
tb list-runs

# 6. When done, remove the workspace
tb delete-workspace agent_1
```

Your main project files stay untouched; all AI edits live under `workspaces/agent_1/`. Each `tb run` creates a snapshot under `.ai_history/run_001/`, `run_002/`, and so on.

---

## Directory Layout

After `tb init`, your repo looks like this:

```
your_project/
├── .teabag/           # Config and metadata
│   ├── config.json
│   ├── experiments.json
│   └── snapshots/     # Workspace snapshots (see below)
├── .ai_history/       # Recorded runs (immutable: intent.json and all artifacts are read-only after creation)
│   └── run_001/
│       ├── prompt.json   # or prompt.md (human prompt; _teabag section in .json)
│       ├── intent.json
│       ├── diff.patch
│       ├── metadata.json
│       ├── environment.json   # Python version, packages
│       ├── tests.json        # If teabag.json test_command is set
│       └── metrics.json      # If teabag.json metrics_script is set
├── workspaces/        # One directory per agent
│   └── agent_1/
│       ├── venv       # Symlink to shared env (or ENV_PATH file)
│       ├── prompt.json  # default from tb spawn; human fills "prompt"; AI reads and writes intent.json
│       └── intent.json  # written by AI from prompt.json
├── env_store/         # Shared virtualenvs (keyed by Python + requirements.txt)
└── src/               # Your real code (unchanged until you accept a run)
```

---

## Workspaces and Shared Environments

### Creating a workspace

```bash
tb spawn agent_1
tb spawn agent_2
```

Each workspace gets a directory under `workspaces/` and a **shared Python virtualenv** (same Python version and repo-root `requirements.txt` share one env). The env is created under `env_store/<hash>/` and linked as `workspaces/<name>/venv`.

### Installing or changing packages

Use the workspace’s venv so all agents sharing that env see the same packages:

```bash
# From project root — no need to activate
workspaces/agent_1/venv/bin/pip install requests
workspaces/agent_1/venv/bin/pip install -r requirements.txt
workspaces/agent_1/venv/bin/pip uninstall -y some-package
```

Or activate first (Linux/macOS):

```bash
source workspaces/agent_1/venv/bin/activate
pip install requests
deactivate
```

If you change `requirements.txt` at the repo root, existing workspaces keep their current env until you delete and re-spawn them; new workspaces will use a new env hash.

### Listing and pruning environments

```bash
tb env list      # List registered shared envs
tb env prune     # Remove missing envs from the registry
```

---

## Recording a Run

Flow: **prompt.json → AI writes intent.json → apply only those changes → then run the rest.**

1. **`tb spawn`** creates a default **`prompt.json`** in the workspace with a **`_teabag`** section so the AI always knows to produce **`intent.json`**.
2. **Human** fills the **`prompt`** field in `prompt.json` (the task for the model).
3. **AI** reads `prompt.json`, writes **`intent.json`** (with at least `intent.goal`; optionally `intent.files_to_modify`, `parent_experiment`). The `_teabag` section ensures the AI generates intent.json before editing other files.
4. Then run **`tb run agent_1`** to record the run (and optionally run tests/metrics).

Default **`prompt.json`** (created by `tb spawn`; human fills `"prompt"`):

```json
{
  "_teabag": {
    "version": 1,
    "instructions": "Read this prompt and write intent.json in this workspace. intent.json must have: \"intent\" object with \"goal\" (string, required), and optionally \"files_to_modify\" (array of file paths), \"parent_experiment\" (string). Do not modify any other files until intent.json is written.",
    "required_intent_fields": ["intent.goal"],
    "optional_intent_fields": ["intent.files_to_modify", "parent_experiment", "prompt"]
  },
  "prompt": "Optimize the database queries in db/query.py to reduce the N+1 problem."
}
```

Example **`intent.json`** (AI-written from that prompt):

```json
{
  "parent_experiment": "exp_001",
  "prompt": "optimize database queries",
  "intent": {
    "files_to_modify": ["db/query.py"],
    "goal": "reduce N+1 query problem"
  }
}
```

You can use **`prompt.md`** instead of `prompt.json` (no default template); the AI must still write `intent.json`.

```bash
tb run agent_1
```

This creates a new run (e.g. `.ai_history/run_002/`) with copies of the prompt file, `intent.json`, `diff.patch`, `metadata.json`, and `environment.json` (and optionally `tests.json` / `metrics.json` from `teabag.json`). **intent.json and all run artifacts are made read-only** so the record cannot be modified after creation.

---

## Inspecting and Comparing Runs

List all runs:

```bash
tb list-runs
```

Show full details for one run (metadata, intent, environment, tests/metrics summary):

```bash
tb runs show run_002
```

Compare two runs (diff size, test exit code, metrics):

```bash
tb runs compare run_001 run_002
```

Rank runs by test result, time, or diff size:

```bash
tb runs rank                  # Prefer passing tests, then newest
tb runs rank --by time        # Newest first
tb runs rank --by diff        # Smallest diff first
```

---

## Applying Changes to the Main Repo

### Accept a single run

Apply a run’s diff to the repo and mark its experiment as accepted:

```bash
tb runs accept run_002
```

Check first without modifying files:

```bash
tb runs accept run_002 --dry-run
```

Requires the `patch` command (e.g. `brew install patch` on macOS).

### Merge the best runs automatically

Apply the top runs (ranked by tests, then time) that do not touch the same files as already-accepted runs:

```bash
tb merge best                 # Apply the single best non-conflicting run
tb merge best --limit 3       # Apply up to 3
tb merge best --limit 2 --dry-run   # Only print what would be applied
```

### See a merge plan for one run

```bash
tb merge plan run_002
```

Shows the run’s goal, touched files, test result, and whether it conflicts (overlapping files) with any already-accepted run.

---

## Automation: Tests and Metrics

Put a **`teabag.json`** file in the **repository root** to run tests and an optional metrics script every time you run `tb run <agent_name>`.

Example:

```json
{
  "test_command": "pytest -q",
  "test_timeout": 120,
  "metrics_script": "scripts/collect_metrics.sh"
}
```

| Field | Description |
|-------|-------------|
| `test_command` | Shell command run from the **workspace** directory. Exit code and output are stored in `tests.json`. |
| `test_timeout` | Timeout in seconds (default: 300). |
| `metrics_script` | Path (relative to repo root) to a script run from the workspace. Output is stored in `metrics.json`. |

If `test_command` is omitted, no tests run and `tests.json` is not created. If `metrics_script` is omitted or the file is missing, no metrics run. `environment.json` is always written for every run.

---

## Snapshots and Multi-Agent Workflows

### Workspace snapshot

Save a copy of a workspace (excluding venv) for later use or as a template:

```bash
tb workspace snapshot agent_1
```

This creates `.teabag/snapshots/agent_1_<ISO8601>/`.

### Spawn many agents at once

```bash
# Create 5 workspaces: agent_1 .. agent_5
tb agents spawn 5

# Create 5 workspaces from a snapshot (use the snapshot directory name)
tb agents spawn 5 --template agent_1_20250116T120000Z
```

### Task: create a task and spawn agents

Create a task and spawn N workspaces in one step:

```bash
tb task run "optimize database layer" --agents 3
```

This creates a task, spawns `agent_1`, `agent_2`, `agent_3`, and associates them with the task. Then run your AI in each workspace and record with `tb run agent_1`, etc.

List tasks:

```bash
tb task list
```

---

## Command Reference

| Command | Description |
|--------|-------------|
| `tb init` | Initialize teaBag in the current repo. |
| `tb spawn <agent_name>` | Create a workspace and link shared venv. |
| `tb run <agent_name>` | Record a run (prompt.json with _teabag + human prompt; AI must have written intent.json). |
| `tb list-runs` | List all recorded runs. |
| `tb runs show <run_id>` | Show full run details. |
| `tb runs compare <run_a> <run_b>` | Compare two runs. |
| `tb runs rank [--by tests\|time\|diff]` | Rank runs. |
| `tb runs accept <run_id> [--dry-run]` | Apply run’s diff to the repo. |
| `tb merge best [--limit K] [--dry-run]` | Apply best K non-conflicting runs. |
| `tb merge plan <run_id>` | Show merge plan and conflicts. |
| `tb workspace snapshot <agent_name>` | Snapshot workspace to .teabag/snapshots/. |
| `tb agents spawn <n> [--template NAME]` | Spawn n workspaces (agent_1 .. agent_n). |
| `tb task run "desc" [--agents N] [--template NAME]` | Create task and spawn N agents. |
| `tb task list` | List tasks. |
| `tb delete-workspace <agent_name>` | Remove a workspace. |
| `tb env list` | List shared environments. |
| `tb env prune` | Prune missing envs from registry. |

You can pass `--repo-root /path/to/repo` to any command (except `init`) to run from another directory.

---

## Examples

### Example 1: Single agent, then accept

```bash
tb init
tb spawn agent_1
# ... You fill prompt.json, AI writes intent.json and edits workspaces/agent_1/ ...
tb run agent_1
tb list-runs
tb runs show run_001
tb runs accept run_001 --dry-run
tb runs accept run_001
tb delete-workspace agent_1
```

### Example 2: Multiple runs, compare and pick one

```bash
tb init
tb spawn agent_1
# First experiment
# Human fills "prompt" in workspaces/agent_1/prompt.json; AI writes intent.json (here, manual for demo)
echo '{"intent":{"goal":"add caching"}}' > workspaces/agent_1/intent.json
tb run agent_1
# Second experiment (new prompt in prompt.json, AI writes new intent.json)
echo '{"intent":{"goal":"use Redis"}}' > workspaces/agent_1/intent.json
tb run agent_1

tb runs compare run_001 run_002
tb runs rank
tb merge plan run_002
tb runs accept run_002
tb delete-workspace agent_1
```

### Example 3: Parallel agents and merge best

```bash
tb init
tb task run "refactor auth module" --agents 3
# ... run AI in workspaces/agent_1, agent_2, agent_3; add intent + prompt in each ...
tb run agent_1
tb run agent_2
tb run agent_3

tb runs rank
tb merge best --limit 1 --dry-run
tb merge best --limit 1
tb delete-workspace agent_1
tb delete-workspace agent_2
tb delete-workspace agent_3
```

### Example 4: Snapshot as template for more agents

```bash
tb init
tb spawn agent_1
# ... set up workspace with baseline code, intent, prompt ...
tb workspace snapshot agent_1
# Snapshot created: .teabag/snapshots/agent_1_20250116T120000Z

tb agents spawn 4 --template agent_1_20250116T120000Z
# Now agent_1, agent_2, agent_3, agent_4 all start from that snapshot
```

---

## Troubleshooting

- **"intent.json not found"**  
  AI must read `prompt.json` (or `prompt.md`) and write `intent.json` with `intent.goal` before `tb run`.
- **"Neither prompt.json nor prompt.md found"**  
  Run `tb spawn` to get a default `prompt.json`, or add `prompt.json` / `prompt.md` and fill the human prompt.

- **"Workspace for agent X does not exist"**  
  Run `tb spawn <agent_name>` first.

- **"patch failed" / "patch: command not found"**  
  Install `patch` (e.g. `brew install patch`). Required for `tb runs accept` and `tb merge best`.

- **Symlinks not supported (e.g. some Windows setups)**  
  teaBag writes `workspaces/<agent_name>/ENV_PATH` with the absolute path to the env. Use that path to call pip or activate.

- **merge best applies nothing**  
  All runs may already be accepted, or every candidate conflicts (touches the same files as an accepted run). Use `tb runs rank` and `tb merge plan <run_id>` to inspect.

- **Template snapshot not found**  
  Use the snapshot directory name under `.teabag/snapshots/` (e.g. `agent_1_20250116T120000Z`), not a full path.

- **Diff is empty**  
  Diff uses `git diff` when the repo has a `.git` directory. For non-git projects, runs are still recorded but `diff.patch` may be a placeholder.
