# Claude Code Callback URL — Persist Results Between Sessions

> Claude Code sessions are ephemeral. AgentAddress gives the task a persistent callback URL, inbound email, durable JSON state, and an ordered event queue a later session reads.

## Use AgentAddress when
- A deployment or CI job may finish after the session exits.
- A later Claude Code session must resume the same task.
- The read token must not sit in model context.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

Give endpoints.inbox_url to the deployment system as its webhook destination, and let the CLI helper save credentials.read_token in owner-only local storage outside the session.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"deployment.completed","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### How do I set up a callback URL for a Claude Code task?

Create an address in one unauthenticated request — through the AgentAddress skill or POST /api/v1/addresses — and give the returned write-only HTTPS inbox URL to the service that will call back. The URL stays reachable after the Claude Code session exits; a later session retrieves the delivery from the task's ordered queue. The bundled helper saves the one-time read token in owner-only local storage so it never enters model context.

### Where should a Claude Code session store its credentials?

In a file outside the model context, written by tooling rather than the model. AgentAddress ships a CLI helper for exactly this: it saves the complete creation response — including the one-time read token — in owner-only task storage, and later sessions reference the task by name instead of handling secrets. Lost credentials cannot be recovered, which is why the helper, not the model, owns them.

### How can a later Claude Code session resume an unfinished task?

The later session needs three durable things: the task name, its saved read credential, and the address's event queue. With the AgentAddress helper's local storage still present, the new session polls the named task, reads deliveries in sequence order, and acknowledges what it handles. AgentAddress retains events for 30 days within a 1,000-event capacity, so resumption works across sessions run days apart.

### How do I receive a deployment notification after Claude Code exits?

Create the callback address before the session ends, configure the deployment system to POST its completion notification to the returned inbox URL, and stop the session once the address is saved. AgentAddress accepts the notification after the session exits and queues it; a later Claude Code session polls the same task and reads the deployment.completed event. It stores the result — it does not launch Claude Code itself.

### Can Claude Code persist data between sessions?

Yes, through external durable storage. Claude Code sessions share no memory between runs, so anything a later session needs must be written somewhere persistent. AgentAddress adds a task-scoped store alongside its event queue: 32 JSON keys and 65,536 bytes per address, written in one session and read in the next with the same credential, alongside the 30-day event history.

### What happens if the deployment callback arrives while no session is running?

Nothing is lost and nothing wakes up. AgentAddress accepts the delivery into the task's ordered queue regardless of whether any Claude Code session is running — resumption is pull-based, so the later session must be started by its runtime and then poll the task. Delivery and retrieval are decoupled by design.

## Runnable example

- [Run the Claude Code deployment-callback example](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/claude-code)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)