Connect your agent

Your agent is an AI agent like Pi, Claude Code, or Antigravity CLI (agy), running on your computer. Connecting it lets it work from everything your project already knows: the tasks with their acceptance criteria, the decisions and conventions your team recorded, your documents and past sessions. When it finishes, it records what it did, so the work shows up on the item, the commit links back, and your team can follow it without asking. DevSpec works with Pi, Claude Code, and Antigravity CLI.

You connect once per computer with an access token from Agent setup. After that your agent connects whenever you start it in a project folder, and appears on the project's Agents page. To hand it work once it's connected, see Working with your agents.

Choose Pi, Claude Code, or Antigravity CLI

DevSpec supports three terminal coding agents. All three run on your machine, use your own model subscription or API key, and get the same DevSpec features.

• Pi is the one we recommend. It's an open source agent that works with whatever model subscription or API key you already have.
• Claude Code is Anthropic's terminal coding agent.
• Antigravity CLI (agy) is Google's terminal coding agent. Note that DevSpec connects to Antigravity CLI in your terminal, not the Antigravity IDE.

One practical difference: from the DevSpec web app you can stop your Pi agent mid-task and change its model or thinking level. Claude Code and Antigravity CLI are stopped from their own terminals.

You can connect any or all of them, on as many computers as you like, and run several copies at once. Each running copy appears on the Agents page with its own codename, so you can tell two of the same tool apart.

Connect from the app

DevSpec walks you through connecting in the Connect your agent step. You'll see it during setup, and it lives permanently on Agent setup, where you can come back to connect another agent at any time.

Pick the agent you use and your operating system (macOS, Linux, or Windows), and its steps appear below as one numbered list, in the order you do them. Your access token sits in the step that needs it: show it and copy it, or create one right there if you don't have one yet. The same steps are repeated below for Claude Code, Pi, and Antigravity CLI.

Under the last step, a status line turns green by itself once that agent connects, usually within a few seconds of starting it in your project's folder. If it keeps waiting, it tells you what to check. During setup you can skip the step: you can always talk to Dev without an agent, and connect one later.

Access tokens

An access token is how your agent proves it's you. Manage tokens on Agent setup.

• Each token is you. It reaches every project you're a member of, with your role in each one. Any of your tokens works in any agent on any computer: reuse one, or make one per computer, whichever is easier.
• Read & write or Read only. When you create a token you choose its access. Read & write lets the agent update tasks and add commits as well as read. An agent needs Read & write: a Read only token can look things up but can't put your agent on the Agents page or record work.
• Up to 10 tokens. Most people need one. A second, read-only token is useful for a tool that should only look.
• Reveal it again. You can reveal and copy a token on the page whenever you connect something new.
• No expiry. Tokens stay active until you revoke them. The page shows when each token was last used, so you can spot ones nobody uses.
• Revoke at any time. Revoking disconnects every tool using that token within seconds. It can't be undone.

If you're removed from a project, your token stops reaching it. Keep your token out of anything you commit: it starts with dvs_.

Connect Claude Code step by step

The DevSpec plugin is the whole connection for Claude Code, and it's required: it's what brings DevSpec's rules, instructions and messages into Claude Code. It adds the DevSpec tools and connection/project commands, so there are no config files to edit.

1. Make sure you have Node.js 18 or later. The plugin runs on it, and Claude Code's own installer doesn't include it. Check with node --version; if it's missing or older, install it from nodejs.org. Without it the plugin can't connect Claude Code to DevSpec.

2. Install the DevSpec plugin. No local clone is needed — inside Claude Code, run:

/plugin marketplace add DevSpecAI/devspec-claude-plugin
/plugin install devspec@devspec
/reload-plugins

Then open /plugin → Marketplaces → devspec and choose Enable auto-update so Claude Code installs new plugin releases automatically when it starts.

3. Paste your token when Claude Code asks. It asks for your DevSpec token while it installs the plugin. Paste your dvs_… token (Read & write). Claude Code stores it on your machine. To change it later, open /plugin → Installed → DevSpec.

4. Optional — recommended for phone and voice control: skip permission prompts. By default, Claude Code pauses in the terminal and waits for your approval before editing files or running commands. When you're driving it from your phone or by voice, turning permission prompts off keeps work from stalling at your computer while Claude Code's built-in safety checks remain in place. You can either add "permissions": { "defaultMode": "bypassPermissions" } to ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json on Windows) or start Claude Code with claude --dangerously-skip-permissions.

5. Start Claude Code and connect to your project. If it's already open, restart it. If you open Claude Code in the folder on your computer where you cloned the Git repository linked to your DevSpec project, it connects to that project automatically and shows up on the Agents page. If you open it in another folder or want to switch projects, run /devspec:devspec.project inside Claude Code. Waiting costs nothing: it only starts working when someone asks it to.

Claude Code's DevSpec commands

The plugin adds Remote, Remote Stop and Project commands. You rarely need to connect by hand, because Claude Code connects by itself when it starts in a project folder. Everything else is a sentence: "Work on DevSpec task 4f2a", "Log a DevSpec task for the login bug", "What did we decide about caching?"

/devspec:devspec.remote connects this Claude Code conversation to DevSpec by hand:

/devspec:devspec.remote-stop disconnects this conversation only. The agent goes offline on the Agents page straight away, other Claude Code terminals on the same machine stay connected, and the session history is kept. If you close Claude Code without it, the agent shows as offline shortly afterwards.

To stop Claude Code connecting when it starts, switch off the plugin setting Make Claude Code available on DevSpec when it starts (it's on by default). You can still connect by hand with /devspec:devspec.remote.

/devspec:devspec.project shows the current project and folder default. Add choose, remember or forget to manage them. See Choose a project for one conversation.

This is DevSpec's own connection. It isn't the same thing as Claude Code's built-in /remote-control.

Connect Pi step by step

DevSpec's Pi package is the whole connection for Pi: there's no DevSpec MCP server to configure. Use Pi 1.0 or later.

1. Install Pi. Pi is the agent you run as pi. On macOS and Linux:

curl -fsSL https://pi.dev/install.sh | sh

On Windows PowerShell:

powershell -c "irm https://pi.dev/install.ps1 | iex"

2. Install the DevSpec package. Install it from npm at user level (without -l) so every folder has DevSpec:

pi install npm:@devspecai/pi-plugin

No separate DevSpec MCP server is needed. (If you prefer to install directly from GitHub, you can also run pi install git:github.com/DevSpecAI/DevSpec-Pi. If you added DevSpec to Pi's /mcp settings earlier, the package disables that duplicate entry so its tools aren't loaded twice.)

3. Log in. In Pi, run /devspec.login with your token from Agent setup:

/devspec.login dvs_your_token_here

From then on, Pi connects to DevSpec by itself whenever you start it in the folder where you cloned your project's Git repository, and shows up on the Agents page. If you open Pi in another folder or want to switch projects, run /devspec.project. This applies to interactive Pi sessions; scripts and one-off runs don't connect on their own.

Connect Antigravity CLI step by step

DevSpec connects to Antigravity CLI (agy in your terminal, not the Antigravity IDE). If you haven't installed Antigravity CLI yet, install it from antigravity.google/download#antigravity-cli:

curl -fsSL https://antigravity.google/cli/install.sh | bash

On Windows PowerShell:

irm https://antigravity.google/cli/install.ps1 | iex

You then configure the DevSpec MCP server once in your home folder and install the DevSpec plugin so every project has DevSpec's rules, tool schemas, instructions and messages.

1. Make sure you have Node.js 18 or later. The DevSpec plugin runs on Node.js. Check with node --version; if it's missing or older, install it from nodejs.org.

2. Add your DevSpec token. Open ~/.gemini/config/mcp_config.json (%USERPROFILE%\.gemini\config\mcp_config.json on Windows) in a text editor and merge in the devspec entry with your dvs_… token (do not use agy mcp add --header, which leaves your token in shell history). On macOS and Linux, make the folder and file readable only by you (chmod 700 ~/.gemini/config && chmod 600 ~/.gemini/config/mcp_config.json).

3. Install the DevSpec plugin. Install the plugin once in your terminal:

agy plugin install https://github.com/DevSpecAI/DevSpec-Antigravity-Plugin

(Or clone it directly with git clone https://github.com/DevSpecAI/DevSpec-Antigravity-Plugin.git ~/.gemini/config/plugins/devspec, using %USERPROFILE%\.gemini\config\plugins\devspec on Windows.)

4. Optional — recommended for phone and voice control: skip permission prompts. By default, Antigravity CLI pauses in the terminal waiting for your approval before editing files or running commands. Starting it with agy --dangerously-skip-permissions keeps phone and voice work from stalling at your computer while built-in AI safety protections remain in place (or run plain agy when working at your desk).

5. Start Antigravity CLI and connect to your project. Run agy (or agy --dangerously-skip-permissions) in your terminal. If you open it in the folder on your computer where you cloned the Git repository linked to your project, it matches that project automatically. If you open it in another folder or want to switch projects, run /devspec-project inside Antigravity CLI. When you want to control it from your phone or the web, run /devspec-remote (and /devspec-remote-stop when you're done).

Antigravity CLI's DevSpec commands

The DevSpec plugin adds these commands to Antigravity CLI (agy). Everything else can be asked in plain words.

Pi's DevSpec commands

The DevSpec package adds these commands to Pi. As with Claude Code and Antigravity CLI, you can also ask for anything in plain words.

How your agent finds the right project

Your agent connects by itself only in a folder that belongs to one of your DevSpec projects. A folder belongs to a project in one of two ways:

• It's a repository the project tracks. The agent matches the folder's git remote to the repositories connected in the project's settings. If the same repository is tracked by more than one project you can access, a folder pin can choose among them. Without a usable pin or an explicit project choice, the connection needs you to choose; it never picks a project at random.
• It's pinned to the project. A small file, .devspec/project.json, names the project. This is how you link a folder that has no repository yet, for example when you plan a project in DevSpec before the code exists.

You do not need a pin just to choose a project. Use a conversation choice first, then Remember only if you want future connections from the folder to use it. For a folder that has no code yet, you can also ask your agent to pin it to a named project; it should confirm the project and file before writing. Pi's existing /devspec.pin <project-id> command remains available. The pin contains only { "project_id": "<full-project-id>" }, not a token or machine-specific path.

The pin holds the project's id, so moving or renaming the folder doesn't break it. It can be committed, but teammates still need access to that project. When the remote matches exactly one accessible project, that match wins over a stale pin. When it matches several, a pin naming one of those projects resolves the choice. An inaccessible pin is ignored.

Choose a project for one conversation

Most starts need no choice: keep launching Pi, Claude Code or Antigravity CLI normally when the repository remote or an existing folder pin already identifies the project. You only need to choose when a repository is linked to several projects you can access, when you start in a folder with no repository, or when you want to switch projects deliberately.

Pi

Choose by project name at launch or while connecting:

pi --devspec-project "Client Website"
/devspec.remote --project "Client Website"

You can also open /devspec.project and pick Choose project (or /devspec.project choose). The choice applies to this conversation (including when you resume it and when it calls DevSpec tools), not to every Pi window open in that folder.

Claude Code

Use the plugin's command:

/devspec:devspec.remote --project "Client Website"

Or run /devspec:devspec.project and use choose to pick from your accessible projects. The selection stays with that local Claude Code conversation, including when resumed, and applies to ordinary DevSpec tools as well as Remote.

Antigravity CLI

Run /devspec-project (or /devspec-remote --project "Client Website") inside Antigravity CLI to see the current project or choose a different one for that conversation.

Two conversations in the same folder can use different projects at the same time. If you name a project you don't have access to, the agent tells you rather than falling back to another project.

Find the project ID and connection details

You normally choose projects by name rather than copying IDs. When you do need a project's full ID:

• Pi: open /devspec.project → Project details, or run /devspec.project status.
• Claude Code: run /devspec:devspec.project to see the selected project's full ID and folder default.
• Antigravity CLI: run /devspec-project to see the selected project's full ID and folder default.
• In the web app: open the project; its ID is the code after /projects/ in the browser address bar.

Remember or forget a folder default

Choosing a project for a conversation does not write .devspec/project.json. Saving a folder default is a separate, explicit choice:

The plugin shows the .devspec/project.json file it will change and asks before writing or removing it. Because a linked git worktree can inherit a pin from its main checkout, check project details afterward if you want to confirm whether an inherited pin is still in effect.

Remember and forget affect future connections that use the folder default. They do not disconnect or redirect conversations that have already selected a project.

Switch projects without carrying old context

Switching an existing conversation to a different project starts a fresh local conversation, so context from the first project isn't carried into the second. Changing your token, removing a pin, or joining a different DevSpec session room does not clear your agent's local conversation history.

• Pi: /devspec.project choose offers a new local conversation for the new project so previous model context is not carried across.
• Claude Code: /devspec:devspec.project choose prepares a fresh conversation for the new project and gives you a claude --session-id … command to run in a new terminal. (/clear stays on the same project; it is not a way to switch projects.)
• Antigravity CLI: start a fresh agy conversation when switching to another project and run /devspec-project.

Keep these three choices separate: the project selects the DevSpec knowledge and work; a DevSpec session is the room you join with Remote's --session; your local conversation is the agent's own history on your machine.

Update before using new commands

Update the installed plugin and reload your agent when new commands ship:

• Pi: run pi update npm:@devspecai/pi-plugin in a terminal, then run /reload or restart Pi.
• Claude Code: update the installed DevSpec plugin through /plugin (or turn on Enable auto-update under /plugin → Marketplaces → devspec), then run /reload-plugins and start a fresh conversation.
• Antigravity CLI: re-run agy plugin install https://github.com/DevSpecAI/DevSpec-Antigravity-Plugin in a terminal on macOS, Linux, or Windows (or if you cloned with Git, run git -C ~/.gemini/config/plugins/devspec pull on macOS/Linux or git -C %USERPROFILE%\.gemini\config\plugins\devspec pull on Windows) and start a fresh agy session.

Check that your agent is connected

To check the whole chain, ask your agent:

Run the DevSpec connection check

It confirms who you're connected as. If you're in the Connect your agent step, its status turns green at the same moment. In Pi, /devspec.status shows the same thing.

Then open the project's Agents page (under Build in the project sidebar). A connected agent appears there within a few seconds, named after its tool and codename, for example "Claude Code · Colorful Possum", ready to take work. Your Agent setup also lists the tools that have connected as you under Connected as you, with when each was last seen.

Commit tags, and when Claude Code refuses a commit

Your agent tags each commit with the task it belongs to, in the form [devspec:<id>]. The tag is how DevSpec links the commit, and later the deploy, back to the item, so you can see what shipped and when. See Commit tracking.

The Claude Code plugin checks commits that Claude makes in a folder pinned to a DevSpec project:

• If Claude is working on exactly one item and the message has no tag, the plugin adds the tag for it.
• If there's no tag and Claude isn't working on exactly one item, the plugin refuses that commit. It also refuses a tag that points to no item in this project, which is usually a mistyped id.

A refusal isn't an error you have to fix by hand. It tells Claude how to recover: find the task that covers the change, or create a small one, put its tag in the message and commit again. Claude normally does this by itself in the same turn. If it's working on several items, the refusal lists their tags so it can pick the right one. Nothing else is blocked: editing files and every other command carry on as normal, and commits you make yourself aren't affected.

What your agent can read and change

Your agent uses DevSpec's tools by itself when it needs something. You don't call them; you ask in plain words.

What it can read, in every project your token reaches:

• projects, their repositories and a summary of recent activity
• tasks, with their intent, acceptance criteria, history, related items and linked commits
• memories: your team's decisions, conventions, insights and risks, current versions only unless it asks for history
• open questions and the project's Still to Discuss points
• sessions, their transcripts, and search across past sessions
• documents and artifacts
• your connected database's structure
• goals, the Review queue, pull requests and testing notes
• the project's rules for agents, and your personal agent rules
• these help docs, for questions about DevSpec itself

What it can change, with a Read & write token:

• create and update tasks, take the ones you ask it to work on, and record what it did with its commits and test results
• check acceptance criteria and record the evidence
• write commit messages with the item's tag, and link commits to items
• record new memories, and update or retire ones that changed
• create and update artifacts such as plans and guides
• post in a session, keep a shared plan up to date, open a poll, or ask one person a question
• update project and personal agent rules, following the project's approval rules
• explain Review questions and record your decisions, including accepting a proposal, answering a conflict or resolving a duplicate

Every change records who made it and when. Your agent stops at Implemented and never marks work Done; see How an item reaches Done.

Agents without the DevSpec plugin

An agent connected with only an access token, without the DevSpec plugin, can still read everything above and record its work. What it can't do is anything where DevSpec has to send it messages, because only the plugin keeps that channel open:

• be driven from a session or your phone
• join a session
• run automations
• run a shared plan in a session

It also doesn't hear about findings on its work while it works (they still appear on the item, in Review and in your notifications), and DevSpec can't tell who asked for each change, so its changes are judged as yours. Its results carry a short note saying so. To get everything, connect Pi, Claude Code or Antigravity CLI with its DevSpec plugin.

What your role means for your agent

Your agent acts with the project permissions of the person asking it. It records who requested the work as well as which agent carried it out.

• Viewers can discuss and read, but cannot change the project's work or knowledge.
• Reviewed Contributors can propose work and knowledge for a Maintainer to accept.
• Contributors can add work and knowledge directly. Edits to agreed work need approval; knowledge edits depend on whose decision they affect.
• Maintainers manage the project and accept proposals. Undoing another Maintainer's decision still needs that person's OK or the project lead's.

You can give an answer through your agent when it is yours to give. Another person's agreement is sent to them to confirm. A pending change leaves the agreed record in force.

Automations have an extra safeguard: new memories and documents, and changes that overrule agreed content, wait as proposals. Leaving your agent to finish a task you asked for does not turn that task into an automation. See Review and Organizations, members and roles.

Rules your agent follows

Your agent's DevSpec plugin gives it the rules in force for the project, so it works the way your team does without being told each time:

• Your personal agent rules, which you set under Personal agent rules on Agent setup. These are yours: DevSpec gives them to every agent you connect, in every project.
• The project's Principles, from Project settings → Agent rules, which Dev also follows.
• The project's Agent execution rules, from Project settings → Agent rules: the mechanics of building and shipping, such as checks to run before pushing and files it must never touch.

When a rule changes, the plugin brings the new version to your agent, and a new conversation always starts with the current rules. See Rules and instructions for how the layers fit together.

If your agent doesn't appear

If your agent isn't on the Agents page after you start it:

• Check the folder. It must be a repository the project tracks, or a folder pinned with .devspec/project.json. See How your agent finds the right project.
• Check the token. It must be Read & write. In Claude Code, re-enter it in /plugin → Installed → DevSpec. In Pi, run /devspec.status, and /devspec.login if you're not connected. In Antigravity CLI, check ~/.gemini/config/mcp_config.json. Reveal the token on Agent setup rather than making a new one, unless it was revoked.
• Check Node.js (Claude Code and Antigravity CLI). Run node --version in the same terminal; you need 18 or later.
• Check connecting at startup. In Claude Code, check the plugin setting Make Claude Code available on DevSpec when it starts. In Pi, check /devspec.remote auto. In Antigravity CLI, run /devspec-remote to connect the terminal session.
• Connect by hand. /devspec:devspec.remote in Claude Code, /devspec.remote in Pi, or /devspec-remote in Antigravity CLI.

If the DevSpec tools are missing from a conversation, start a new one: tools load when a conversation starts. In Claude Code, run /reload-plugins after installing.

If your agent hits a rate limit

Each access token can make about 60 DevSpec tool calls a minute. Staying connected and waiting for messages don't count toward that. If an agent goes over, the tool call comes back with an error asking it to retry after a number of seconds, and a well-behaved agent waits and carries on by itself.

Because all your agents share your one token, several busy agents share the same allowance. If they keep hitting it, give them fewer overlapping tasks at once.