Docs

Agents

Follow your coding agents on the map. Open Agents beside it to see every Claude Code and Codex session at work: each file they read, edit or search lights up in the session's color, as it happens.

Agents is about what your agents do. To have one explain the code on the map, connect it over MCP: see Explanations. The two work side by side.

Connect an agent

Agents learn about Codiluce through their hooks. Start the map for the repository, then open Agents → Agent connections in the panel's footer. Choose Codex or Claude Code, copy the configuration and merge its hooks entries into the agent's settings, keeping the ones you have:

  • Claude Code: .claude/settings.local.json in the repository. Restart Claude Code if the running session does not pick up the settings.
  • Codex: .codex/hooks.json in the repository. Review and trust the hooks with /hooks; hooks must be enabled in Codex.

The command line prints the same configuration:

npx codiluce activity hooks --agent claude-code
npx codiluce activity hooks --agent codex

Add --repo PATH for another repository or worktree, and --state-dir PATH if the map uses a custom state directory. Codiluce never changes your agents' configuration itself. The connections window says whether a configuration was found, whether Codex trusts it, and when the last hook arrived; run any action in your agent to confirm delivery.

What you see

  • Sessions, with their title and status: running, waiting, idle (a turn ended, not the session), finished. A status no hook has confirmed for five minutes shows as unknown.
  • Recent activity: each read, edit, search, command and test run, newest first. Select a session to see only its activity, on the list and on the map.
  • Marks on the map: the file an agent touched is outlined in its session's color with what it did, and the mark fades over 30 seconds. A search outlines the folder it searched, dashed. Zoomed out, marks gather on the closed folder that holds them.
  • Two sessions on one file show both marks. That signals overlap, not a proven conflict.
  • Click a path in the feed to reveal that file on the map, even one hidden from the map. If the file was added after the last analysis, this click updates the index first.

Show activity on the map turns the marks off and on. Marks belong to the working tree, so they are hidden while you look at a past commit in History.

What is observed, and what is not

Only what an agent's hooks report, with a session behind it. There is no file-system watcher, so a change no hook reported is not attributed to anyone.

  • File reads and edits, patches (including both paths of a move) and the folders that searches name carry their paths.
  • A few literal shell reads (cat, head, tail, sed -n) and simple rg or grep searches are read as such. Pipelines, scripts and unfamiliar commands stay plain commands, with no file claimed.
  • Known test commands are shown as test runs.
  • A search marks the folder it searched, not every file it matched.
  • A started action is an attempt; only its completion confirms it.

Privacy

The hook forwards each event to the map on your own machine and sends nothing back to the agent. Codiluce keeps paths, search queries, tool names, session titles and statuses, in memory only: at most 500 events and 100 sessions, gone when the map stops. Prompts, transcripts, file contents, patch bodies and command output are discarded on arrival. No API key or model is involved. serve --read-only turns activity off.