Plugin Commands
The DevSpec plugin ships two commands, and both of them do the same kind of thing: connect this agent to DevSpec, and disconnect it. They exist because connecting runs a real setup — resolving the project, pinning the folder, registering the connection, starting the poller — that a model would improvise badly.
Everything else you might want is a sentence. The MCP server gives your agent the tools; you say what you want in plain language. There used to be eleven commands here, and nine of them were a paragraph of prose telling a model to call one tool it could already see.
This page is specifically for Claude Code. The Codex plugin exposes workflows as skills, not custom
/devspec-*slash commands; see Connecting Codex.
Prerequisites
Before using plugin commands, ensure you have the following set up.
- Claude Code v2.0 or later installed.
- A DevSpec MCP token generated (Settings > MCP Tokens in the DevSpec web UI).
- MCP connection configured in Claude Code (via
claude mcp addor manual.mcp.json). - The DevSpec plugin installed (run
/plugin install devspec@devspecin Claude Code).
If you haven't connected DevSpec to Claude Code yet, see the MCP Endpoint docs for setup instructions.
Quick Reference
All available commands at a glance.
| Name | Scope | Description |
|---|---|---|
/devspec.remote | read-write | Connect this local agent as a DevSpec remote-control target. Default: opens a new private channel with a unique friendly name (e.g. Colorful Possum · Grok Build · host · repo) for this local agent conversation. Soft-reconnect only after a recent stop in the same conversation (bond-scoped, never by repo/cwd). Pass --session <uuid> to attach to a known session (Agents “Connect”); --new forces a fresh channel. Mirrors turns and polls from the Agents page / phone. Not Claude's built-in /remote-control. |
/devspec.remote-stop | read-write | Disconnect remote control — marks the Agents page offline and stops the poller for that session only (other terminals’ remotes stay live). History is kept; soft-rejoin only if you remote again soon in the same conversation. |
Core Workflow
There are two commands, and neither of them does your work. /devspec.remote
connects this agent to DevSpec; /devspec.remote-stop disconnects it. Everything
else is a sentence.
Once the DevSpec MCP server is connected, ask for what you want in plain language and the agent calls the right tool:
| You say | What happens |
|---|---|
"Work on action item 4f2a" | The agent reserves it so no other agent takes it mid-run, claims it, implements it in an isolated worktree, and records what it did |
"Work these in order: 4f2a, 9c1b, 2e7d" | One agent holds all three and works them one at a time |
| "Log a DevSpec item for the login bug" | create_action_item, with the intent and acceptance criteria filled in |
| "I just finished the caching fix — record it" | record_completed_work, inferred from your git log and diff |
"Generate the commit message for 4f2a" | generate_commit_message, including the [devspec:<id>] deployment-tracking tag |
"Link commit a1b2c3d to 4f2a" | add_commit_reference |
| "How do I set up a deployment target?" | devspec_help_search against the product docs |
This is not a workaround for missing commands — it is the point. A slash command only works where that plugin is installed, and it becomes a lie the moment the plugin drops it. A sentence works in any host with the MCP server, including one nobody has written a plugin for.
The DevSpec web app's copy buttons emit exactly these instructions, so "copy" and "type it yourself" produce the same thing.
Troubleshooting
Common issues and how to resolve them.
Command not recognized
Claude Code doesn't show the /devspec.* commands in the palette.
Ensure the plugin is installed by running /plugin install devspec@devspec in Claude Code, then run /reload-plugins. The commands are auto-discovered from the plugin's commands/ directory.
MCP token not configured
Commands fail with an authentication error.
Generate a token in DevSpec (Settings > MCP Tokens), then add it to Claude Code via claude mcp add or your .mcp.json configuration file.
Read-only token on write commands
A write tool like create_action_item fails with a scope error.
Write commands require a read-write token. Generate a new token with read-write scope in DevSpec Settings > MCP Tokens.
DevSpec server unreachable
Commands timeout or fail with a connection error.
Check that the DevSpec URL in your MCP configuration is correct and the service is running. If using a self-hosted instance, verify the server is accessible.