Troubleshooting

This page covers the problems people most often run into with DevSpec, each with what causes it and how to fix it. Most messages in DevSpec name the cause and who can fix it, so start with the exact wording you see.

If your problem isn't here, use Ask DevSpec from the ? menu in the header, or contact the team. See Getting help.

Your agent doesn't appear on the Agents page

Your agent (Pi, Claude Code or Antigravity CLI) appears on a project's Agents page when it's running on your machine and connected to DevSpec. If it isn't there, check these in order:

1. It's running in the project's folder. An agent connects by itself only when you start it in a folder that belongs to the project: a clone of a repository the project tracks, or a folder pinned to the project with a .devspec/project.json file. Started anywhere else, it stays out of the way. In Antigravity CLI (agy), run /devspec-remote to register the terminal session for phone and web control.

2. Its token can write. Your access token, from Agent setup, must be Read & write. A read-only token can't put an agent on the Agents page.

3. It can reach DevSpec. Ask your agent:

   Run the DevSpec connection check
   

   Follow the reason returned by the check. If the token is missing or revoked, reconnect with a valid token from Agent setup. If more than one project matches the folder, choose the project with /devspec.project in Pi, /devspec:devspec.project in Claude Code, or /devspec-project in Antigravity CLI. In Pi, /devspec.status shows the current connection.

4. Claude Code and Antigravity CLI have what they need. Both plugins need Node.js 18 or later on your PATH; check with node --version. In Claude Code, if the plugin's commands don't appear in the / menu, reinstall it with /plugin install devspec@devspec, then run /reload-plugins. Connecting at startup can be switched off in Claude Code's settings (Make Claude Code available on DevSpec when it starts), so check it's on.

For a folder with no repository, create the pin from the project's Setup guide (choose I don't have a repository yet, then copy the command it shows), or ask your agent to pin the folder to the project. See Connect your agent.

An item is stuck as Reserved by an agent that went offline

When an agent takes a task, the item shows Reserved until the agent starts and Working while it works. Other agents skip the item for as long as it's held, so no two agents work on the same thing.

If the agent that reserved an item goes offline (its terminal was closed, or the machine went to sleep), the item stays reserved for a while. DevSpec frees work the agent hadn't started within about 15 minutes of it disconnecting, and work it had started after 24 hours. It doesn't hand the item to another agent: it just becomes free again.

To free it sooner, press Release next to the "held by" note, on the item or on the Agents page under Work in flight, and say why. Contributors and Maintainers can do this. Then hand the item to another agent, or to the same one once it's back, with Agent command or Tasks → Hand off. See Working with your agents.

Work is waiting for someone's OK

Open the item's waiting label to see the decision involved and who can answer. The agent can continue on its own branch, but must not merge the change until it has the required OK. Ask the named person to decide, or use Talk it through to discuss an alternative.

An Experiment needs permission to land too. See Review.

A change you asked for is still pending

A pending change is saved for approval; it has not replaced the agreed record. Open it in Review to see who can decide. If it is waiting for you, decide there or tell Dev or your agent what you want.

A request to confirm is asking you to agree to a specific answer yourself. Read the answer, then confirm or decline it. The proposing agent does not need to be online. See Review.

Your repository isn't indexing or looks out of date

DevSpec indexes each repository's Tracking branch so Dev and your agents can search your code. You can see a repository's state on its card in Project settings → Repositories.

• No tracking branch. A repository without one can't be indexed. The Setup guide shows Choose a branch to watch; pick a branch on the repository's card. The branch must already exist on GitHub.
• An error message on the card. The card says whose problem it is. If it needs you (usually GitHub access), follow what it asks. If the problem is with the provider or on DevSpec's side, the card says you don't need to do anything.
• Out of date. The card shows how many commits behind the index is. Use Check for updates (the icon button on the card) to check GitHub and bring the index up to date, or Full reindex to rebuild the index from scratch.
• Some files failed. The card shows the number of failed files. Use Retry failed files. If the clone itself failed, use Retry clone & index.
• Your organization's balance is empty. Indexing is background work that pauses at $0 and resumes when funds are added. An Owner or Admin adds funds in Settings → Billing.

Some file types are never indexed, and each repository has an editable list of ignored paths on its card. See Code indexing.

While a repository is being re-indexed, the session header shows Indexing... (hover to see which repository is updating and Responses may have incomplete context). That clears when indexing finishes.

DevSpec says pushes aren't arriving

Each repository card in Project settings → Repositories shows Receiving your pushes once pushes arrive, or Pushes aren't arriving when they stop reaching DevSpec. When pushes aren't arriving, DevSpec's index and commit tracking fall behind.

Choose Fix next to Pushes aren't arriving. DevSpec works out the cause and shows the fix for it, for example:

• DevSpec's GitHub app hasn't been given access to the repository, so you manage the app's access on GitHub or install it on a different GitHub account
• the app has been suspended on GitHub, so a GitHub owner restores its access there
• the problem is on DevSpec's side, and there's nothing for you to change

After fixing it, choose Test it now and push a commit. The status turns to Receiving your pushes when the push arrives.

DevSpec also checks each repository regularly and catches up on pushes it missed, so a short outage doesn't leave the index stale for long. Changing your organization's GitHub access needs an organization Owner or Admin. See Repositories and GitHub.

Deploys don't show on the Delivery page

The Delivery page shows deploys from your connected hosts (Vercel or Coolify). If yours don't appear:

• No deployment target yet. Connect your host under Project settings → Integrations → Deployment targets (Maintainers only). The Delivery page shows a setup checklist until one is connected.
• The host isn't sending notifications. After you create a target, its setup panel gives you a webhook URL to add in your host. For Vercel, add it under your Vercel project's Settings → Webhooks with the deployment events the panel lists. Vercel webhooks need a Vercel Pro or Enterprise plan. For Coolify, paste the complete URL, including its secret, into Coolify's webhook notification settings.
• The deploy is for a branch the target doesn't follow. A deployment target follows its repository's tracking branch. If your host deploys a different branch, the target shows Deploys are arriving for a branch you don't track with a button to track that branch instead. Or change the repository's tracking branch.
• The Coolify app isn't added. Coolify sends one webhook for your whole team, and DevSpec ignores deploys for applications you haven't added as targets.

"Webhook signature is failing"

This banner on a deployment target means your host is sending deploys, but DevSpec rejected them because the signature didn't match. The webhook secret saved in DevSpec differs from the one your host signs with.

For Vercel, copy the signing secret from your Vercel webhook and paste it into DevSpec with Update webhook secret. For Coolify, DevSpec creates the secret and puts it in the webhook URL: use Regenerate webhook secret, then paste the new complete URL into Coolify. The old URL stops working immediately.

See Delivery.

Dev or voice says a limit was reached or funds have run out

When Dev or voice can't run, the message names the limit that stopped it. Posting to a room is free and continues while paid work is paused, until an organization becomes read-only. Here's what each message means and who can change it:

A limit stops the next request, not the one that reached it: the reply or recording that uses up the last of an allowance, a project's cap or the balance finishes and is charged in full. That's why an allowance or a cap can read slightly over, and the balance slightly below $0; the next funds added pay that back first.

At $0 the app stays usable for 30 days: you can read, post to rooms and manage your work, and connected agents keep working. Dev, reading aloud and voice input pause, and so does background work such as indexing, which catches up once funds are added. If no funds are added within 30 days, the organization becomes read-only: everyone can still sign in, read and export, but nothing can be created or changed until funds are added. Turning on auto top-up in Settings → Billing keeps the balance from running out. See Billing, usage and limits.

You can't create a project

Two things decide whether you can create a project:

• Your organization role. Only organization Owners and Admins create projects. If you're a Member, the Create project form says "Only organization owners and admins can create projects". Ask an Owner or Admin to create it and add you, or to make you an Admin.
• The organization's balance. An organization with no money can't create projects, because projects index code and run background work that's charged to the balance. The message reads "Add funds to your organization to create projects". An Owner or Admin adds funds in Settings → Billing.

Your first organization starts with $15, so this usually comes up in an additional organization you created later, which starts at $0.

To create a project, open All projects in the sidebar and choose New project. See Projects.

You can't start a session

Every project member, including a Viewer, can open a room or start a session with a connected agent. Dev does not need to be switched on for those choices.

If you are starting with Dev, check that Dev is enabled for you, the organization has funds, and your personal and project spending limits have not been reached. An Owner or Admin changes these under Settings → Usage & limits. See Dev or voice says a limit was reached.

If the organization has become read-only after 30 days without funds, no new sessions can be created until an Owner or Admin adds funds.

If you can't find a way to start a session at all, check you're in the right project: sessions belong to a project, and Sessions → New session is on the project's sidebar under Plan. See Sessions.

Dev doesn't reply to your message

In a session, the Send to picker beside the send button decides who hears your message. A new session starts on Post to room, which is for your team: Dev doesn't reply. This is the most common reason Dev stays quiet.

To ask Dev, pick Dev in Send to, or type @Dev in your message. An @Dev mention calls Dev even when you're posting to the room. DevSpec remembers your choice for each session.

If you did send to Dev and your message shows a failure instead of a reply, the message on it says why: a limit (see Dev or voice says a limit was reached) or that the conversation is too long (see Context limit reached). See Sessions.

Your message fails with "Context limit reached"

Dev holds the whole conversation in mind when it replies. As a session grows, DevSpec condenses older history so the conversation can keep going, and you'll see a divider reading Earlier context summarized. Eventually a very long session is full, and a message to Dev fails with Context limit reached.

Start a new session for the next part of the work. Nothing is lost:

• The old session keeps its whole transcript, and you can still post to its room.
• Tasks, memories and documents the session produced stay in the project, where Dev finds them from any session.
• In the new session, ask Dev to pick up where you left off. Dev can search past sessions, so name the old one or what you were discussing.
• To bring specific messages across, open a message's menu in the old session, choose Select messages, pick the messages, and start another session with them.

See Sessions.

Voice or the microphone doesn't work

Voice has two halves: the microphone in the message box, which turns your speech into text, and read-aloud, which speaks replies. The message you see tells you which part failed:

• Microphone permission denied. Your browser blocked the microphone. Allow it for DevSpec in your browser's site settings, then try again.
• No microphone found or Could not use a microphone on this device. Connect a microphone, or choose a different one under Microphone → Input device in the composer's settings (the gear by the message box).
• Microphone is busy. Close any other app or tab using the microphone.
• Voice not supported. Your browser can't record audio. Use an up-to-date desktop or mobile browser.
• Voice isn't turned on for your account. An organization Owner or Admin can turn Voice on for you in Settings → Usage & limits → People.
• A limit or out-of-funds message. Read-aloud is charged to the balance; see Dev or voice says a limit was reached.

Speech-to-text understands English only. If replies aren't read aloud, check Settings → Replies & voice → Playback: Silent plays nothing automatically, Beep plays a chime, and Voice reads new messages aloud. You can also play any message on demand. See Voice.

A teammate can't see a project or a session

What someone can open depends on their organization role, the project's access setting, and the session's visibility.

For a project:

• A project set to Available to everyone opens for every organization Member. A project set to Invite only opens only for people added to it.
• Guests see only the projects they've been added to.
• Owners and Admins can open every project in the organization.

To add someone, a project Maintainer opens the project's Members page and uses Add from organization or Invite someone. Someone who isn't in your organization yet gets an invitation and appears once they accept.

For a session, check its Visibility in the session settings:

• Shared ("Project team") sessions open for everyone on the project.
• Restricted ("Specific people") sessions open only for the access list. The session's creator or a project Maintainer adds people with Manage who can join… on the People tab.
• Private ("Only you") sessions are hidden from everyone else, including Maintainers and organization Admins.

Mentioning someone with @ in a session also gives them access to it. See Organizations, members and roles and Sessions.

The Claude Code plugin refused a commit

In a folder pinned to a DevSpec project, the DevSpec plugin for Claude Code checks commits that Claude makes, so each one links to a task. It refuses a commit in three cases, with a message starting "DevSpec:":

• The commit has no [devspec:<id>] tag and Claude isn't working on exactly one item. When Claude is working on exactly one item, the plugin adds the tag for you. With none, it can't know which item the commit belongs to.
• Claude is working on several items and the commit doesn't say which one it's for.
• The tag names an item that isn't in this project, usually a mistyped ID or an item from another project.

To recover, tell Claude which item the commit is for, or ask it to find or create a small task that covers the change, then retry the commit. The refusal blocks only that one commit; nothing else Claude does is affected.

The check applies only to commits Claude Code makes through the plugin in a pinned folder. It's there to keep every change traceable to its item; it isn't a security control, and commits you make yourself aren't affected. See Commit tracking.

You can't sign in

If you can't get into your account, use the public contact page. It works without signing in. Choose I can't access my account and give us the email address you signed up with, and the team will help you get back in.

The contact page asks for your name and email address, since you're not signed in, and the team replies to the address you give. It also covers other topics, such as I need help with DevSpec and Billing question, if you don't have an account yet.

If you can sign in but can't see an organization or project you expect, the problem is access rather than sign-in; see A teammate can't see a project or a session.