Messages

APX logs every interaction — agent runs, Telegram chats, direct calls — as JSONL messages. These logs are local to your machine and never committed.

Channels

Every message belongs to a channel that describes its origin:

Channel	What it captures	Where it lives
`runtime`	`apx run` invocations — prompt in, response out	`~/.apx/projects/<id>/messages/`
`a2a`	Agent-to-agent calls made from within a session	`~/.apx/projects/<id>/messages/`
`exec`	Quick `apx exec` calls	`~/.apx/projects/<id>/messages/`
`telegram`	Telegram bot messages	`~/.apx/messages/telegram/` (global — not per project)

Message format

Each line in a .jsonl file is one message:

{
  "id": "msg_01abc...",
  "ts": "2026-05-30T14:22:01.123Z",
  "channel": "runtime",
  "type": "agent",
  "actor_id": "reviewer",
  "project_id": "077078af9dd7",
  "content": "I reviewed the diff. The main issue is..."
}

The type field distinguishes participants in a thread:

`type`	Who sent it
`user`	A human (CLI, Telegram, web)
`agent`	An APX project agent
`tool`	A tool call or tool result
`system`	An internal APX system message

The actor_id carries the specific identity — a Telegram user id, an agent slug, or "apx" for the super-agent — so chat views can distinguish who is talking.

Commands

Tail recent messages

apx messages tail                              # last 50 messages, all channels
apx messages tail --channel runtime            # only agent run messages
apx messages tail --channel telegram           # only Telegram messages
apx messages tail -n 100                       # increase the limit

apx

$ apx messages tail
2026-06-14 09:30:51  ← telegram  alex: deploy the staging branch
2026-06-14 09:30:52  → telegram  roby: on it — handing this to backend
2026-06-14 09:31:02  → runtime   sofia: spawned claude-code (exit 0, 4.2s)
2026-06-14 09:31:48  ← web       alex: any failing tests?
2026-06-14 09:31:50  → agent     backend: cart total test is flaky, retrying

apx messages tail — recent messages with type, actor, and content

Chat view

The chat subcommand formats messages as a readable transcript, grouping by actor and highlighting user vs. agent turns:

apx messages chat                              # all channels, chat format
apx messages chat --channel telegram           # Telegram conversation
apx messages chat --channel runtime -n 20

apx

$ apx messages chat --channel telegram -n 20
[2026-06-14 09:30:51] user alex: deploy the staging branch
[2026-06-14 09:30:52] super-agent roby: On it — handing this to the backend agent.
[2026-06-14 09:31:50] agent backend: Deploy queued. The cart total test is flaky;
retrying once before I promote the build.
[2026-06-14 09:32:31] super-agent roby: Done — staging is live on commit a1f3c92.

apx messages chat --channel telegram — formatted conversation view

Search

apx messages search "deploy"                   # full-text search in message logs
apx messages search "bug" --channel runtime

Storage layout

Per-project messages are partitioned by date:

~/.apx/projects/<apx_id>/messages/
├── 2026-05-28.jsonl
├── 2026-05-29.jsonl
└── 2026-05-30.jsonl

Telegram messages are stored globally (not per-project) because a single bot can serve multiple projects:

~/.apx/messages/telegram/
└── 2026-05-30.jsonl

Sessions — higher-level invocation records that complement message logs.
Projects — where <apx_id> comes from.