# Getting Started: Your First Trace


Gemba is the agent-runtime platform. It runs one loop: stand up, run, see,
remember, and measure. This page covers the first three steps. You start with
nothing installed and you finish with one captured trace you can read.

## Prerequisites

- Node.js 22+ and npm
- An Anthropic API key
- The `apm` agent package manager in your terminal
- An empty scratch directory, because the agent writes files where it runs

Put the key in the environment before the first run:

```sh
export ANTHROPIC_API_KEY=<your-anthropic-api-key>
```

## Install the skill pack

The pack carries the six platform skills. They teach a coding agent the command
family and the published actions.

```sh
apm install forwardimpact/gemba-skills
```

## Install the command family

One npm package ships every `gemba-*` command:

```sh
npm install -g @forwardimpact/gemba
gemba-harness --help
```

To run one command without a global install, call it through `npx`:

```sh
npx gemba-harness --help
```

The steps below use `npx`. Drop that prefix when you installed the package
globally.

## Write the task

A task is a plain markdown file. It states what the agent must do. Keep the
first one small and checkable.

```md
<!-- first-task.md -->
Create a file named `greeting.js` in the current directory. Export one
function `greet(name)` that returns the string `Hello, <name>!`. Then create
`greeting.test.js` with one `node:test` case that checks `greet("world")`.
Create no other file.
```

## Run one session

`gemba-harness run` gives the task to a single agent and lets it work alone.
Run this from your scratch directory:

```sh
npx gemba-harness run \
  --task-file=first-task.md \
  --cwd=. \
  --allowed-tools=Read,Glob,Grep,Write \
  --max-turns=20 \
  --output=trace.ndjson
```

Readable text streams to your terminal while the raw NDJSON trace lands in
`trace.ndjson`. Each flag does one thing:

- `--task-file` names the markdown task. `--task-text` takes the prompt inline
  instead.
- `--cwd` is the directory the agent works in. Keep it a scratch directory.
- `--allowed-tools` is the tool allowlist. The default also allows `Bash`,
  `Edit`, `Agent`, and `TodoWrite`, so this run is deliberately narrower.
- `--max-turns` caps the agentic turns. The default is 50, and `0` removes the
  cap.
- `--output` writes the trace to a file. Without the flag, the NDJSON goes to
  stdout.

The command exits `0` when the session succeeded. It exits `1` when the session
errored. Add `--agent-model` to run a different Claude model.

## Read the trace

`gemba-trace` queries the file `gemba-harness` wrote. Start with the overview:

```sh
npx gemba-trace overview --file trace.ndjson
```

```text
metadata: {"timestamp":"2026-08-26T09:14:02.118Z","sessionId":"b7c1a0d2","model":"claude-opus-4-8[1m]","claudeCodeVersion":"2.0.31"}
summary: {"result":"success","isError":false,"totalCostUsd":0.0412,"durationMs":41883,"numTurns":6}
turnCount: 11
resultEventTurns: 6
turnPopulations: {"turnCount":"rendered-trace-turns","resultEventTurns":"result-event-turns"}
tools: [{"tool":"Write","count":2},{"tool":"Read","count":1}]
taskPrompt: Create a file named greeting.js in the current directory.
```

Every object value prints on one line, and the sample is abridged. `turnCount`
counts the turns the trace holds. `resultEventTurns` counts the turns the model
reported. Add `--format json` for the machine-readable shape.

## Run the same loop in CI

The
[`forwardimpact/gemba-bootstrap`](https://github.com/forwardimpact/gemba-bootstrap)
action installs the pinned toolchain and the platform CLIs on a GitHub Actions
runner. Name the commands you need in its `clis` input, pin the action to a full
commit SHA, and read
[Automate with GitHub Actions](/docs/prove-changes/run-benchmark/ci-workflow/)
for a complete workflow.

## Verify

Your first trace is good when all of the following hold.

- **The session exited `0`.** Run `echo $?` straight after the harness command.
- **The trace parses.** `npx gemba-trace count --file trace.ndjson` prints an
  integer turn count above zero. The reader skips an unparseable line silently,
  so a count well below the turns you expected is the signal that a line is
  malformed.
- **The overview reports success.** The `summary` line carries
  `"result":"success"` and `"isError":false`.
- **The agent stayed inside the allowlist.** The `tools` line names `Write` and
  names nothing you left out of `--allowed-tools`.
- **The work landed.** Your scratch directory holds `greeting.js` and
  `greeting.test.js`.

## What's next

<div class="grid">

<a href="../coordinate-team/">
<h3>Coordinate an Agent Team</h3>
<p>Run a lead and N participant agents in one asynchronous session. Choose supervise, facilitate, or discuss. Pass messages with Ask, Answer, and Announce. One NDJSON trace records everything that happened.</p>
</a>
<a href="../prove-changes/">
<h3>Prove Agent Changes</h3>
<p>Reproducible evidence that agent changes improved outcomes, from the eval session through the trace analysis.</p>
</a>
<a href="../prove-changes/run-eval/">
<h3>Run an Eval</h3>
<p>Run an agent-as-judge eval in CI and get a traceable verdict on whether an agent change improved outcomes.</p>
</a>
<a href="../prove-changes/trace-analysis/">
<h3>Analyze Traces</h3>
<p>See exactly what an agent did and why. Download traces, query turns, filter by tool or error, and measure token cost.</p>
</a>
<a href="../predictable-team/">
<h3>Set Up Persistent Memory and Metrics</h3>
<p>Give your agent team persistent memory and real signal detection with wiki-backed state and XmR control charts. Get evidence that agents act on changes. They do not act on noise.</p>
</a>

</div>