# Nests Agent Protocol

Nests makes agent working memory portable across coding harnesses. It stores
repo-scoped snapshots containing compiled context, handoffs, observed events,
diffs, and registered artifacts.

## Cold Start

When you begin work in a repository, do not assume the absence of `.nests/`
means no Nest exists. Absence means discovery should run first.

Run:

```bash
nests status
```

If `.nests/config.json` exists, Nests compares the local snapshot with the
configured remote.

If `.nests/config.json` is absent, Nests computes a repo fingerprint from the
git remote when available and checks whether an accessible Nest is known for
that repo.

Possible outcomes:

```text
Remote differs. Run: nests pull
```

```text
Discovered remote: nests://project-slug
Run: nests pull nests://project-slug
```

```text
No accessible Nest found for this repo.
Run: nests init
```

If offline or unauthenticated, treat the result as unknown rather than proof
that no Nest exists.

## Startup

After pulling or confirming the local snapshot is current, read context:

```bash
nests context --for codex
nests context --for claude
nests context --for agent
```

Continue from the handoff if present, but verify claims against observed
evidence. Reports and handoffs are agent-authored claims. Diffs, file state,
events, command outputs, and artifacts are evidence.

## During Work

Record important claims:

```bash
nests report "<claim or progress update>"
```

Register important outputs:

```bash
nests artifact add <path>
```

Use normal project verification before claiming completion.

## Handoff

Before ending work or asking another agent to continue:

```bash
nests snapshot -m "<what changed and what remains>"
nests share
```

If the next agent or device needs access through a link:

```bash
nests share
```

The share command returns an agent link and a human link. Agent links are meant
for tools and harnesses. Human links are meant for timeline, diff, artifact,
and admin views.

## Harnesses

For Codex, repo setup may include:

```bash
nests init --codex
```

This writes project-local `AGENTS.md` guidance and `.codex/hooks.json` hooks.
Codex should still require the user to review and trust project hooks.

For Claude Code, the equivalent adapter should inject startup context through
Claude hooks and write `CLAUDE.md` guidance.

For generic agents, this file and `/agents/nests.md` are the reference.

## Safety

- Do not silently pull remote memory unless the repo or user opted into Nests.
- Do not treat agent claims as verified facts.
- Do not share snapshots without considering secrets and private repo data.
- Prefer visible commands and explicit links during early adoption.