Agent Integration

Lovelace integrates with Claude Code, OpenCode, and Codex. The desktop app installs everything for each one, in one click; you don’t need Node or any separate runtime. A small headless helper ships with the app and backs all three integrations.

What gets installed

All three integrations expose the same MCP server tools (the 8 tools below) and the same two commands: ticket <id> to load and start a ticket, done to self-check acceptance criteria, update the ticket’s status and write the session. They are slash commands on Claude Code and OpenCode, and skills invoked as $ticket and $done on Codex. An opt-in prepare-commit-msg Git hook, installed by any integration, inserts the active ticket ID into your commit messages; each detects the others’ copy, so installing several integrations is safe. Every install is additive: Lovelace merges into or appends to existing files and never overwrites anything outside its own sections.

Claude Code

• An MCP server, registered through a project-scoped .mcp.json.
• Hooks in .claude/settings.json:
  • SessionStart injects the project digest, so the session opens oriented.
  • Stop checks that a session record was written for the active ticket.
  • PreToolUse steers raw file writes to .lovelace/tickets/ toward the tools.
  • Four lightweight presence hooks: one starts a per-session marker on your first prompt, every tool call keeps it warm, set_active_ticket ties it to a ticket, and it clears when the session ends. The app shows a live ring and elapsed timer on the card an agent is working; a marker goes stale after 15 minutes by default.
• A pointer in CLAUDE.md to .lovelace/AGENTS.md, a regenerated file that holds the rules of engagement.

OpenCode

• An MCP server, registered under the mcp key in opencode.json.
• .lovelace/AGENTS.md added to the instructions array in opencode.json, with a Lovelace-owned section in the root AGENTS.md pointing to it.
• Slash commands in .opencode/commands/.
• One Lovelace-managed plugin, .opencode/plugins/lovelace.js, carrying the presence hooks, the write guard, the digest and the session-record check. It calls the same headless helper as Claude Code.

OpenCode’s plugin API covers the same ground, with three differences: the digest arrives appended to the first prompt of the session rather than before it; the session-record check can’t block a session from finishing, so it nudges on the next message instead; and presence clearing at session end is best effort, with the marker going stale within the timeout regardless.

Codex

• An MCP server, registered in a Lovelace-owned section of .codex/config.toml.
• Hooks in .codex/hooks.json. Codex’s hooks framework carries the same events and payloads as Claude Code’s, so the session-start digest and the session-record check behave exactly as they do there, backed by the same helper. The write guard runs there too; Codex documents tool hooks as a guardrail rather than a hard enforcement boundary.
• Skills at .agents/skills/: the ticket and done commands, invoked as $ticket and $done.
• A Lovelace section in the root AGENTS.md directing the agent to .lovelace/AGENTS.md.

Codex applies two one-time trust gates: the project must be trusted before the MCP server and hooks load (the AGENTS.md section and the skills work regardless), and the hooks must also be reviewed and trusted with /hooks, again after a reinstall changes them. A few behaviors are weaker than on Claude Code: presence beats ride only local tool calls, so hosted tools such as web search don’t refresh them; presence clearing at session end is advisory, with the marker going stale within the timeout regardless; and the root AGENTS.md section is a directive the agent follows rather than an automatic include, softened by the digest arriving at every session start.

The MCP tools

Tool	Purpose
create_ticket	Validate fields against the schema, assign an ID, write the file
update_ticket	Update fields and status; reject edits to locked core fields
describe_schema	Return the project’s types, fields, statuses and priorities
query_tickets	Filter by status, type, assignee, parent or any defined field
read_document	Return a document’s body, or a directory’s landing page plus child summaries
log_session	Write an append-only session record
set_active_ticket	Record the ticket the session is working on
search	Plain-text search across entity bodies and titles

Every mutation re-indexes. Because the agent works through the same validated core as the app, it can never produce a file the validator would reject, and you watch each move land on the board in real time.

The digest

At session start the agent receives a compact orientation summary: tickets in progress and ready to pick up, the last few session records (outcome and open questions), and any validation errors or warnings. It’s plain text, kept small, designed to be dropped straight into context.