Verified against Agent Island v1.7.1 on 2026-07-31. The released macOS and Windows builds classify local Claude Code and Codex session records. They do not discover sessions through a hosted Agent Island account.
Confirm that the coding session has written local evidence
Open the Claude Code or Codex session and send one normal prompt. Wait until the tool writes its next event. A terminal window by itself does not create a session record, and a shell waiting at a prompt does not prove that a transcript exists.
Agent Island watches session files and also runs a periodic recovery scan. If a newly written event appears after the app starts, the native file watcher should request a rescan. The polling path repairs a missed or coalesced filesystem notification.
Check the roots for your platform
Default Claude Code project transcripts live under these roots:
# macOS and Windows user profile
~/.claude/projects
~/.config/claude/projectsOn Windows, CLAUDE_CONFIG_DIR can override the default roots. Agent Island accepts a comma-separated value and appends projects to each configured root. If Claude Code writes to a custom directory but Agent Island starts without the same environment, the two processes can see different roots.
Codex sessions use ~/.codex/sessions by default. On Windows, CODEX_HOME can move that root. Claude Desktop session metadata is separate from Claude Code transcripts: macOS stores it under ~/Library/Application Support/Claude/claude-code-sessions, while Windows uses the equivalent directory under roaming application data.
A session file needs an identity
Codex rollout files begin with a session_meta record. Agent Island reads the session ID and working directory from that first JSONL line. A truncated, foreign, or partially written first record cannot identify the session yet.
Claude Code normally uses the transcript filename as the session ID. Claude Desktop metadata can add the title, working directory, archived state, and last activity time. A CLI-only transcript can still appear without a Desktop title; the app falls back to the working directory or session ID for its label.
Old evidence becomes idle
The monitor is designed to show current work, not every historical transcript forever. Released state logic uses a bounded attention window and orders sessions by semantic activity. A session with no recent event can correctly disappear from the active surface or read as idle even though its transcript remains on disk.
Test with a fresh prompt before changing file permissions or deleting settings. Touching a transcript timestamp manually is a poor test because the classifier prefers timestamps carried by semantic events when they are available.
Some session types are filtered on purpose
Claude Code subagent transcripts and Codex spawned or automation rollouts can finish many times during one user task. Agent Island separates those records from the user's interactive thread. Subagent alarms are opt-in, and automation records do not become normal your-turn alerts.
An archived Claude Desktop thread is also omitted from the active picker. These filters prevent a fan-out worker or old thread from looking like the session that needs your attention.
Verify local file access without sharing the files
Agent Island needs read access to the relevant session directories. On macOS, a privacy restriction or a root owned by another account can block enumeration. On Windows, an inaccessible directory is skipped so one bad subtree does not break the entire scan.
You can verify the shape of a root without opening transcript contents:
# macOS
find ~/.codex/sessions -name '*.jsonl' -maxdepth 5 | head
find ~/.claude/projects -name '*.jsonl' -maxdepth 5 | head
# Windows PowerShell
Get-ChildItem "$HOME\.codex\sessions" -Filter *.jsonl -Recurse | Select-Object -First 5
Get-ChildItem "$HOME\.claude\projects" -Filter *.jsonl -Recurse | Select-Object -First 5The output paths can contain private project names. Redact them before posting an issue. A useful report can say that five JSONL files exist and the newest file changed at a given time without attaching their contents.
Separate detection from status classification
A visible session with an unexpected state is a different problem from a missing session. Claude completion depends on assistant stop reasons while ignoring API-error envelopes and unrelated sidechain traffic. Codex completion depends on ordered user/start and turn/completed evidence. A quiet file alone does not mean the turn finished.
When the session appears but the state is wrong, record the provider, expected state, visible state, and event time. Do not paste the transcript. A minimal synthetic event sequence is safer and easier to test.
Use restart as a diagnostic, not a repair strategy
Restarting Agent Island rebuilds watcher registrations and runs a new scan. If a fresh session appears only after every restart, the likely fault is the event path or a root created after startup. If the session remains absent, compare the configured roots and local file access.
Repeated reinstalls do not change where Claude Code or Codex writes sessions. Confirm the data path before replacing the app.
Report the smallest reproducible boundary
Include Agent Island version, operating system, provider, default or custom session root, whether a fresh JSONL file exists, and whether restart changes the result. Exclude transcript text, API keys, tokens, OAuth records, and private repository names.
If Agent Island itself does not launch, use the install and update checklist first.