Documentation / Agentic Workflows

Agentic Workflows

Aphotic surfaces what your AI coding sessions are actually doing in several places, not one tab: a live, zoomable graph of tool calls as they happen, a full workspace tool for digging through run evidence and replaying a finished session, and a notch tile that carries status at a glance. This page covers the whole surface — what each piece is, how the opt-ins work, and exactly what is and isn’t collected. Everything here is opt-in at two levels: the ai layer at install time, and then whichever of the individual plugins below you actually want — see Plugin System for why this lives as plugins rather than base-shell features.

What you get

Agent Graph tab (Command Center, SUPER+D, the agent-graph plugin) — a live node graph of the active session(s): tool calls, subagent spawns, and their parent/child relationships, rendered as they happen. Pan, zoom, and a detail level that thins out as the graph grows so it stays legible on modest hardware. Every finished run is archived, so you can scrub through it after the fact with the same play/pause/seek transport, not just watch live.
Agent Audit (the agent-audit plugin) — a full workspace tool for inspecting local agent run evidence: live activity plus replay timelines over the same event history Agent Graph draws from. It opens on its own plane, not a Command Center tab — see Supported Features for the SUPER+SHIFT+W workspace host this and any future plugin tool of its shape use.
Agent Notch Tile (the agent-notch-tile plugin) — docks into the notch popout: a waiting-for-input badge, the active harness and phase, a live subagent count, today’s token usage, and the local provider’s GPU VRAM claim.
Agent bar icon — a switchable bar icon covering whichever harnesses you’ve installed the matching plugin for (Claude Code, Codex, OpenCode): left-click for a session/token-usage panel, right-click launches the harness in a new terminal, middle-click cycles between them. Ollama isn’t a harness and never gets a tab here — see Plugin System. Each harness’s icon only appears once its own <harness>-hooks plugin is installed and enabled, not merely because the harness is running.
aphotic whatsnew — the release-banner mechanism this feature shipped alongside. Hyprland-native (hyprctl notify), shown once automatically the first time you land on a new Aphotic version.

Turning it on

Two separate opt-ins, both required:

[!IMPORTANT] If you’re upgrading an existing install from before v2.0.0, agent tracking and every surface below are no longer automatic — they were split out of the ai layer into opt-in plugins. Skip straight to step 2 and run the plugin installs below to restore the behavior you had.

1. The ai layer, at install time — see Profiles & Layers for the layer system in general.

./install.sh --with ai              # scripted, no prompts
./install.sh --opt-in               # or the interactive layer picker

The guided setup (./install.sh with no flags, on a terminal) offers it in its “optional extra tool sets” step, where Enter means none; a non-interactive run with no flags installs no optional layers. Either way ai has to be picked explicitly.

2. The plugin(s) you actually want, any time after that, not just during install:

aphotic plugin install agent-graph          # the Command Center tab + replay
aphotic plugin install agent-audit          # the workspace-tool run inspector
aphotic plugin install agent-notch-tile     # the notch tile
aphotic plugin install claude-hooks         # live per-session tracking, per harness --
aphotic plugin install codex-hooks          # install only the ones matching
aphotic plugin install opencode-hooks       # the harness(es) you actually use

Each is independent: agent-graph/agent-audit/agent-notch-tile alone give you their surfaces for whatever presence data is already available; the <harness>-hooks plugins are what upgrade a harness from bar-icon presence into full live per-session detail across all of them. See Plugin System for the full capability model.

What “on” actually does

Selecting ai at install time does two concrete things, both reversible by de-selecting it on a re-run:

Installs Ollama (with the GPU runner for your card), llmfit and Claude Code, and enables a systemd user timer (aphotic-agent-usage.timer) that refreshes aggregate token-usage numbers every 15 minutes.
Unlocks (but doesn’t itself install) the AI-tracking shell surfaces — services/InstallProfile.qml reads aphotic.toml’s resolved layer list, and every plugin that declares the ai layer, plus the bar’s agent icon, is gated on it. Agent Graph, Agent Audit, the Agent Notch Tile and the agent icon are absent, not just idle, when the layer is off. The layer also gates the locally hosted chat providers (Ollama, the Assistant) and the local model hosts’ claims. AI Chat and Intelligence are core and stay available without it, offering Claude, Gemini and ChatGPT.

It does not wire any harness’s hooks and does not install any of the AI-tracking plugins — those are the separate opt-ins from the previous section. A fresh git clone with no aphotic.toml yet (i.e. you haven’t run install.sh at all) is treated as “ai on,” so cloning the repo and running qs -c aphotic directly still shows the full shell for evaluation — though with zero plugins installed, that means no agent bar icon and none of the surfaces above until you install some.

Turning it off

aphotic plugin remove <name> reverses a plugin symmetrically: for a harness-hook plugin, that means the unwire step actually edits the harness’s own config back out (e.g. removing this plugin’s entries from ~/.claude/settings.json) before deleting the plugin’s files; for Agent Graph, Agent Audit, or the Agent Notch Tile, the surface disappears the instant it’s disabled or removed, no leftover UI. De-selecting the ai layer itself on a re-run of install.sh just disables the usage timer and stops Ollama/llmfit from being reinstalled on the next run — it doesn’t touch any plugin you’ve installed, since plugins are opted into (and out of) independently of the layer now.

What’s actually collected

Short version: tool-call metadata, never conversation content.

The hook forwards tool name, duration, session/tool-call id, and subagent parentage — enough to draw the graph, populate Agent Audit’s timelines, and show “Bash, 340ms” in a popout row.
Prompts and responses are never read, stored, or transmitted. The usage-tracking timer separately scans local transcript files for aggregate token counts only (aphotic agent usage-update) — same rule, no message content.
Everything stays local: a rotating event log, a per-session snapshot file, and a per-run replay archive, all under ~/.local/state/aphotic/. Agent Graph, Agent Audit, and the Agent Notch Tile all read from this same local data — none of them is a second collection point. Nothing leaves your machine.