Documentation
Set up and understand
Installation
Download the archive, drag AItention.app into
Applications, launch it. The app is signed with a Developer ID and
notarised by Apple — no warning appears.
The status hooks
Without hooks the app can list which sessions are running, but not
what they are doing. On first launch it offers to set them up: it
adds entries to ~/.claude/settings.json that call a bundled
program. That program writes a status file and does nothing else.
A backup is made before every change to that file. All entries are marked
# aitention so removal never touches hooks you configured
yourself:
~/Applications/AItention.app/Contents/MacOS/AItention --uninstall-hooksThe states
| State | Meaning |
|---|---|
| Decision | Claude has asked a question with options to choose from. |
| Waiting | A question or a permission is pending. |
| Error | The turn failed on an API error — overload, rate limit, billing. |
| Done | The turn finished, the reply is unread. |
| Working | A prompt is running, tools are executing. |
| Subagents | Subagents are running, the main agent waits for them — not for you. |
| Wake-up | Waiting for a wake-up call it set itself — not for you. |
| Ready | Session open, no turn active. |
| Dormant | Ended, but resumable with claude --resume. |
If a working session goes quiet for more than thirty minutes it loses its colour and shows how long it has been silent instead. A stale display that looks confident is worse than one admitting it does not know.
Where the data comes from
Everything the app shows comes from these files. None of it leaves the machine.
| File | What for |
|---|---|
~/.claude/sessions/<pid>.json | Which sessions run, their working directory and origin |
~/.claude/aitention/status/<id>.json | The live state, written by the hook — the only file AItention creates itself |
~/.claude/projects/…/<id>.jsonl | Transcripts: replies, tool calls, tokens |
~/.claude/tasks/<id>/ | A session's task list, if it keeps one |
~/Library/Application Support/Claude/… | Title, model and mode of desktop sessions, plus rate window usage |
~/.codex/sessions/…/rollout-*.jsonl | Codex sessions: title, project, state, context and consumption |
~/.codex/session_index.jsonl | The names Codex gives its sessions |
~/.claude/history.jsonl | Your own prompts — the basis of the prompt search |
Connecting other tools
AItention reads a small JSON file per session at
~/.claude/aitention/status/<session-id>.json. For Claude
Code the bundled hook writes it. Any other tool that can start a
program on events may do the same — and then appears in the list with
no change to AItention.
The contract is published and checked against the source on every build:
aitention.app/schema/status-v1.json.
Three fields are required — session_id, state
and ts. A tool identifies itself with agent
(claude, codex or an identifier of your own);
without the field, claude is assumed. With more than one
tool running, a fourth grouping appears in the list.
What you write, AItention shows — nothing more. It starts nothing, evaluates nothing and forwards nothing.
Previous sessions and prompt search
“Previous sessions” lists everything that can be resumed — across a
restart too. Ordered by application or project, across seven days,
thirty days or the whole period, with a search field. On each row one
click puts the full command on the clipboard:
cd <project folder> && claude --resume <id>
or codex resume <id>. The project folder belongs to it
— without it neither tool finds its session.
If the name escapes you, search your own prompts instead.
~/.claude/history.jsonl is searched; the hit leads to its
session, and the resume command sits next to it.
Codex
Codex sessions appear in the same list as those of Claude Code — with the icon of the application they run in, with project, context and consumption. From two tools onwards, grouping by tool is added. Nothing changes in your Codex setup: Codex keeps its own transcript per session, AItention reads it and does not write to it.
One limitation. AItention does not report the “waiting for you” state for Codex. Claude Code communicates it through the status hook; in Codex transcripts we have not yet found a corresponding event. Codex sessions therefore appear as working, done or failed. As soon as such an event turns up, the state follows.
Activating a licence
After purchase you receive a mail with a button that opens the app and enters the licence. If that does not work: Settings → Licence → paste the key → Activate. No connection is made.
When something is wrong
The diagnostic output shows what the app sees without starting the interface — including every path and the hook status:
~/Applications/AItention.app/Contents/MacOS/AItention --dumpTo check a licence key: --verify-licence <key>