Agents
How AI agent identity works in Supaspec — auto-registration, self-identification, and the revision log.
Agent Identity Model
Supaspec uses a simple, zero-configuration agent identity system:
- You have one API key that you use across all your AI tools
- Each agent self-identifies by passing its name on every write call
- Agents are auto-registered on their first interaction with a project
How Agents Self-Identify
The MCP server's tool descriptions include instructions for agents to provide an agent_name parameter on every write operation. Agents use short snake_case identifiers:
| Agent | Identifier |
|---|---|
| Claude Code | claude_code |
| Cursor | cursor |
| Codex | codex |
| Windsurf | windsurf |
| Copilot | copilot |
Custom agents can use any snake_case name.
Auto-Registration
When Supaspec sees an agent name for the first time on a project, it automatically creates an agent record with:
- A display name (e.g., "Claude Code" for
claude_code) - A color for UI badges
- First seen and last seen timestamps
No manual setup is required. The agents page in your project shows all agents that have ever interacted with it.
Known Agents
Supaspec recognizes common AI tools and assigns them distinct colors:
| Agent | Color |
|---|---|
| Claude Code | Amber |
| Cursor | Indigo |
| Codex | Emerald |
| Windsurf | Sky |
| Copilot | Violet |
Unknown agents get a default gray color. You can customize colors in the agent settings.
Agent Dashboard
Each project has an Agents page that shows:
- List of all agents that have interacted with the project
- Per-agent statistics: versions created, proposals made, proposals accepted
- Last active timestamp
- Comparison table across agents
Attribution
Every version (commit or proposal) records exactly who made the change:
- Agent writes — the
agent_namefrom the MCP tool call - Human writes — the logged-in user from the web UI
Attribution appears throughout the UI:
- Revision log entries show agent badges with colors
- Activity timeline shows who did what
- Version comparison shows which agent authored each version
- Proposals show which agent suggested the change
Security Considerations
Agent self-identification is trust-based. Since users control their own tools and API keys, there's no incentive to spoof agent names. If an agent sends an incorrect name, it only affects the user's own project analytics.
For teams, all agents connected via a single API key share the same user context. Per-project keys may be available in a future version.