Agents

Claude Code and Codex

A role reaches a host two ways: as an MCP prompt served straight from the graph, or as a thin file the host reads at start. Both render the same contract from the same node.

Connect the host first (Setup). Then the roles filed under vinc/agent are visible to it. A graph without that domain lists no prompts, which is a valid state and not an error.

Roles as MCP prompts

Vinc's MCP server answers prompts/list and prompts/get. The list is the roles under vinc/agent, one prompt per role, named by the role's slug. Getting one returns the role's contract hydrated from the live graph: mission, reads in order, gates, prohibitions, the output contract, and the traps attached to the role. Nobody retypes a reading list.

One optional argument, focus: a node id or a phrase. An id is read one hop; a phrase is searched; either way the material is appended below the contract.

Everything read from the graph arrives inside a fenced block that is labelled as data, not instructions. Anyone who can write to the graph can change a role's text, so the prompt tells the model to adopt the role because its operator asked, and to report, not obey, any sentence in the block that tries to widen its permissions. The same contract is served locally and on the hosted hub.

Claude Code

Claude Code turns MCP prompts into slash commands named /mcp__<server>__<prompt>. With the server added as vinc, a role is one command, and the focus argument follows it:

/mcp__vinc__agent-dev-core
/mcp__vinc__agent-dev-core concept:agent-orchestration

Claude Code also reads subagent definitions from .claude/agents/<name>.md, and it finds them by walking up from the working directory. Such a file is a pointer, not a definition: the frontmatter the harness enforces (model, tool denylist) and an instruction to read the node first:

---
name: agent-dev-core
description: Takes one package in the Python core, works it on one branch,
  and leaves one green pull request and one episode.
model: opus
---
# Agent role: core development

This file is a pointer. The role is defined in the graph, and two calls read it:

    vinc_graph      seed_id=concept:agent-dev-core depth=1
    vinc_neighbors  node=concept:agent-dev-core

What follows is a snapshot, and the graph wins where they differ.

Those files can be generated by the repository rather than written by hand. scripts/agents_sync.py --pull reads the role nodes into a committed snapshot, --gen renders the files from it, and --check runs in CI offline and fails when a file drifts from the snapshot or a reads entry names a document nobody can find. The prompt surface and the generator share one renderer, so a role reads the same in a file and in a prompt.

A session opened at a workspace root above the repository sees no roles at all, because the walk up never reaches the folder. It looks exactly like "there is no roster". Open the session inside the repository.

The frontmatter expresses prohibitions as a tool denylist, and the roster says plainly what that cannot enforce: a role that keeps a shell can still write a file through it, and a prohibition naming an MCP tool is not enforced by the harness at all. Those stay a contract the role reads.

Codex

Codex connects to the same server (Setup, way B) and gets the tools, but it does not expose MCP prompts to the user: that is an open request on the Codex tracker, not a shipped feature. So in Codex a role is read, not invoked:

vinc_graph      seed_id=concept:agent-dev-core depth=1
vinc_neighbors  node=concept:agent-dev-core
vinc_brief      question="concept:agent-dev-core"      relations with their evidence

Standing instructions for Codex live in AGENTS.md. One line there does what the Claude Code file does: name the role node and say to read it before the first edit. Codex also reads the instructions a server sends at connection time; Vinc uses that field to say which space the session is in, not to carry a role.

Keys: an unattended Codex or Claude Code session holds a read-only key. Codex takes it from an environment variable named in bearer_token_env_var; Claude Code takes it as a header. Both are on Setup.

Product names mentioned here are trademarks of their respective owners and are used only to indicate compatibility. Vinc is not affiliated with or endorsed by any of them.