An integration is a hook or plugin that shelldeck adds to an agent's own config. It reports the agent's lifecycle (working, blocked on approval, done, idle) straight to the terminal it runs in. It is not the skill: the skill only teaches an agent the sd commands.

Supported now: Claude Code, Codex, Gemini CLI and Devin CLI. Each gets exact state (working, needs you, done) and resume. These four are installed by sd integration install and shown first on the AI agents page.

Every other row below is a preview, to be finished later. It installs with sd integration install <agent> or --all, and it is tested against config files only, not against the running agent.

"Verified against" says where each format was checked. None of them has been run against a signed-in agent yet: that manual check is still on the release checklist.

Without an integration, shelldeck still detects the agent and reads its state from the screen. With one, the AI agents page shows the state as coming from integration.

The formats below follow each agent's hook documentation, as connected by dotpals (Claude, Gemini, Cursor, Copilot, OpenCode) and herdr (Codex, Qwen Code, Qoder, Droid, Devin and the resume commands). Only watching events are used: an integration can never approve, deny or block a tool.

Without installing anything, shelldeck also reads two agents' own logs (source native):

• Codex: the newest rollout in ~/.codex/sessions for the terminal's folder.
  • task_started, a user message or a tool call means working; task_complete means done.
  • The session id gives codex resume <id>.
• Claude Code: ~/.claude/sessions/<pid>.json. busy means working, and its session id gives claude --resume <id>.

A native "working" holds only 15 s past the last log event, so a prompt waiting for approval (the log goes quiet) is picked up by screen detection again. An integration report outranks native, which outranks the screen.

Session id only (Qwen, Qoder, Droid, Grok, Antigravity, Letta, Hermes): herdr found these agents' hook events unreliable for lifecycle, so their hooks report only the session id, for resume. The state stays with screen detection.

Installing needs the agent's config folder (install and run the agent once first). Amp, Kiro, Maki, Cline, Aider, Goose, Crush and the rest keep using screen detection for now (see sd integration list).

When shelldeck starts an agent (spawn, Launch, sd agent start, resume), it builds the command with that agent's own flags (team.launch_line):

Devin's flags (-- "prompt", --model, -r/--resume, -c/--continue, -p) and hook events (SessionStart, UserPromptSubmit, Pre/PostToolUse, PermissionRequest, Stop, PostCompaction, SessionEnd) were cross-checked the same way. Devin rejects its whole hooks block when it holds an unknown event, so shelldeck installs only events from that list (a test guards it). Its shell tool is exec.

A prompt that is longer, or isn't plain words, is written to .shelldeck/prompts/<id>.md. The agent is then asked to read that file, so no shell ever sees quotes or $.

Claude Code 2.1.289's --help confirms --settings <file-or-json>, the positional prompt and --resume. For the other three, the flags come from their docs as used by dotpals and herdr.

sd agent cmd TERMINAL ACTION [ARG] (and the Actions menu on the AI agents page) types the agent's own command:

Sources:

• Claude: the command names in Claude Code 2.1.289's bundle.
• Codex: codex-rs/tui/src/slash_command.rs.
• Gemini: docs/reference/commands.md.
• Devin's list comes from the Devin CLI docs as quoted by web search, plus other projects' Devin integrations (docs.devin.ai and the CLI itself are blocked from this build box).

A command is refused while the agent is blocked (it would answer the question) or working, unless --force. sd agent cmd claude --list shows an agent's commands.

sd integration list            # every agent: method, lifecycle, resume, CLI found, integration status
sd integration detect          # installable agents found on this machine
sd integration install [AGENT...]   # default: every installable agent found
sd integration status [AGENT]
sd integration uninstall AGENT...

The AI agents page has the same controls under Integrations. Installing and removing are host-only (POST/DELETE /api/integrations/{agent}).

Hook agents run "<python>" -m shelldeck.hook <agent> [event] with the event JSON on stdin. <python> is the absolute interpreter shelldeck runs on.

• It reads only the event name, the notification type and message, and the session id. Nothing else leaves the agent's process.
• It posts a report to POST /api/agent-reports with the terminal's SHELLDECK_AGENT_REPORT_TOKEN.
  • The server accepts that token on its own only from this machine, never through a share tunnel.
  • The token opens no other endpoint.
• Outside a shelldeck terminal it does nothing.
• It always exits 0 and prints only the "carry on" reply each agent expects ({"continue":true} for Cursor's beforeSubmitPrompt, {} for Gemini and Cursor).

Reports hold for 60 s (working) or 120 s (other states). After that the screen heuristic decides again, so an agent that dies mid-turn never stays "working".

• Shared configs (Claude, Gemini, Cursor) are merged:
  • Unrelated keys and hooks stay.
  • Only entries whose command contains -m shelldeck.hook <agent> are added or removed.
  • Installing twice changes nothing.
• A config that isn't plain JSON (comments, a bad edit) is left untouched, and the command reports an error.
• The first change keeps <file>.shelldeck-backup, and every write is atomic (temp file + rename).
• Own files (Copilot, OpenCode) put back whatever was there before on uninstall.
• Outdated means the hook's interpreter no longer exists (shelldeck was reinstalled elsewhere) or the event list changed. Reinstall to fix it.

• Status still says screen.
  • The hook only reports inside shelldeck terminals.
  • OpenCode needs a restart after installing.
  • Gemini runs hooks only in trusted folders, and not when hooksConfig.enabled is false.
• Check one event by hand (inside a shelldeck terminal, with an agent running): echo '{"hook_event_name":"PermissionRequest"}' | python -m shelldeck.hook claude, then sd agent status.