> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amika.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture agent sessions

> Capture every Claude Code and Codex session as append-only event files on disk with amikalog.

<Note>
  **Research preview.** Interfaces, config formats, and CLI commands described
  here may change before general availability. Reach out on
  [Discord](https://discord.gg/xDXk4KjGWg) or email
  [help@amika.dev](mailto:help@amika.dev) to join the early access program.
</Note>

[amikalog](https://github.com/gofixpoint/amika#amikalog) is an open-source CLI
that captures every Claude Code and Codex session as plain, append-only files
on disk. Your past agent work becomes data that future agents, scripts, and
pipelines can read, search, and build on. It ships from the `amika` repo but is
a standalone tool — you can use it on its own.

## Install

amikalog is versioned and installed independently of the `amika` CLI. Pass
`--component amikalog` to the [install script](/install):

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/gofixpoint/amika/main/install.sh | sh -s -- --component amikalog
```

Pin a version with `--install-version` (amikalog releases under tags of the
form `amikalog@v*`), or build from source with `make build-amikalog`.

## Turn on capture

Enable capture once, globally:

```bash theme={null}
amikalog start
```

That's it. Use Claude Code and Codex exactly as before — every session is now
recorded. amikalog rides the agents' own hook systems, so there is no daemon,
no proxy, and no change to how you invoke the agent.

`amikalog start` idempotently installs hook entries into:

* `~/.claude/settings.json` — one entry per Claude Code agent-activity hook
  event (tool use, prompts, permissions, subagents, tasks, turns, context
  compaction, and session lifecycle).
* `~/.codex/hooks.json` — one entry per Codex lifecycle event (honors
  `$CODEX_HOME`).

The hooks are global: they fire in every repository. Capture is best-effort —
a failure to record is reported on stderr but never blocks the agent or alters
its behavior.

<Note>
  **Codex requires trusting the hooks before they run.** On first run Codex marks
  newly added hooks for review and skips them until trusted, printing a warning
  that points you to its `/hooks` command — review and trust the amikalog hook
  there, and Codex sessions start producing events. Claude Code needs no such
  step.
</Note>

<Warning>
  Sessions started before `amikalog start` are not captured. Only sessions that
  begin after capture is on produce a record.
</Warning>

To turn capture off, run:

```bash theme={null}
amikalog stop
```

`stop` removes only the hooks amikalog installed; unrelated hooks and
already-captured events are left alone.

## What gets captured

amikalog records every session as append-only JSON events under a predictable
directory tree on your own disk. Each event carries the raw hook payload plus
the git state it fired in — repository, commit, branch, and whether the tree
was dirty.

Events are written under the amika state directory, resolved in order:
`AMIKA_STATE_DIRECTORY` if set, otherwise `$XDG_STATE_HOME/amika`, otherwise
`~/.local/state/amika`. `amikalog start` prints the resolved paths. Events land
at:

```
<state>/events/{claude,codex}/sessions/<ts>_<session-id>.jsonl
```

Each session is a single append-only [JSONL](https://jsonlines.org/) file —
one JSON event per line, and earlier lines are never modified. The files are
ordinary text you can `grep`, `jq`, sync, or load into a database. Each line
records:

| Field        | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `source`     | The agent that fired the hook (`claude` or `codex`)                      |
| `hook_event` | The hook's event name (e.g. `PostToolUse`)                               |
| `session_id` | The agent session the event belongs to                                   |
| `timestamp`  | Capture time (RFC3339 with nanoseconds, UTC)                             |
| `seq`        | The event's position within its session, starting at 0                   |
| `cwd`        | The working directory the hook reported                                  |
| `git`        | Git state of `cwd` (`repo_root`, `commit`, `branch`, `dirty`), or `null` |
| `payload`    | The raw hook payload exactly as the agent provided it                    |

For example, pull every `PostToolUse` event a session recorded:

```bash theme={null}
jq 'select(.hook_event == "PostToolUse")' \
  ~/.local/state/amika/events/claude/sessions/*_3f2a....jsonl
```

## Why capture

Local capture is just JSON on disk, so you can close the loop with whatever you
already have — `jq`, a script, a cron job, or your agent's own file tools. Past
sessions feed forward into future runs:

* **Memory** — have a new session read past sessions' event logs in the same
  repo, so agents stop rediscovering the same context.
* **Guardrails** — mine past sessions for the rules your team keeps learning
  the hard way and write them into the instruction files (`CLAUDE.md`,
  `AGENTS.md`) that future runs load.
* **Evals** — each session is the full sequence of what an agent actually did,
  pinned to the exact commit it ran on. Real sessions make the best test cases.

Claude Code and Codex events share one schema, so anything you build on top
works across agents.

## Share sessions with your org

<Info>
  Org sync is in beta.
</Info>

Local capture works entirely offline. To pool your org's sessions in one
place, two beta commands sync the event log with a storage bucket that the
hosted Amika platform manages for your organization. Both authenticate with an
org API key set in `AMIKA_API_KEY`:

```bash theme={null}
amikalog beta:push          # upload not-yet-pushed events
amikalog beta:fetch <dir>   # download the org bucket into <dir>
```

`beta:push` uploads your not-yet-pushed events to the org bucket. Pushed files
are tracked by size, so repeated runs re-upload only sessions that grew new
events, and re-pushing is idempotent.

`beta:fetch` downloads the org bucket into a local directory — your whole org's
sessions as ordinary files.

<Warning>
  `beta:push` uploads message contents, tool arguments, file paths, and commit
  messages to Amika's servers. Treat captured transcripts the same way you treat
  the source code your agents read.
</Warning>

## Command reference

| Command                     | Description                                                   |
| --------------------------- | ------------------------------------------------------------- |
| `amikalog start`            | Register the amikalog hooks with Claude Code and Codex        |
| `amikalog stop`             | Remove the hooks (already-captured events are kept)           |
| `amikalog beta:push`        | Upload not-yet-pushed events to your org's storage bucket     |
| `amikalog beta:fetch <dir>` | Download the entire org storage bucket into a local directory |
| `amikalog version`          | Print version information                                     |

## Environment variables

| Variable                | Purpose                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `AMIKA_STATE_DIRECTORY` | Override the state directory (else `$XDG_STATE_HOME/amika`, then `~/.local/state/amika`) |
| `AMIKA_API_KEY`         | Org API key for `beta:push` / `beta:fetch`                                               |
| `AMIKA_API_URL`         | Override the API base URL (default `https://app.amika.dev`)                              |
| `CODEX_HOME`            | Override the Codex config directory (default `~/.codex`)                                 |

## Next steps

<CardGroup>
  <Card title="Send a message to an agent" href="/guides/send-a-message-to-an-agent" icon="paper-plane" />

  <Card title="amikalog on GitHub" href="https://github.com/gofixpoint/amika#amikalog" icon="github" />
</CardGroup>