Connecting agents

Connecting an agent gives your AI coding tool live access to the project's specs, decisions, constraints, and tickets through MCP (the Model Context Protocol). You set it up once per project, and Vibeless keeps the agent's configuration current after that.

Where to find it

Open the project, select Dashboard in the sidebar, then the Agents tab. The tab has 4 cards, top to bottom: Connected agents, Hooks, Reports, and Agent-artifact paths.

The new-project setup wizard offers the same install in its final step. If you skip it there, you can install later from this tab.

For the list of tools an agent can call once connected, see MCP tools reference.

How the connection works

• The local server. When the app starts, it runs the bundled vibeless-mcp-server as one local MCP server on a fixed loopback port (127.0.0.1). The port stays the same across restarts. If another program takes it, the app picks a new one and rewrites every installed agent's configuration.
• The manifest. The app writes ~/.vibeless/manifest.json. It lists the app's internal bridge port and every project with its token. The MCP server reads it on every request to work out which project the request belongs to.
• The project token. Each project has its own token, a random 64-character string. The installer writes it into the agent's configuration file as an Authorization: Bearer header. It tells Vibeless which project the agent works on, so an agent never sees another project's data.
• Hooks. A hook is a command the agent runs at a set moment, such as the start of a session. Vibeless installs 2 by default: one injects a project digest when a session starts, and one injects a short reminder each time you send a prompt.

Supported agents

Cursor has no hook system of its own. Vibeless writes a rules file, .cursor/rules/vibeless.md, that tells the agent which Vibeless tools to call at the moments a hook would fire on Claude Code. Following those rules is up to the agent, so this is less reliable than real hooks. The same limit is stated in the rules file itself.

Gemini and Antigravity have tabs in the hook install dialog (see Hooks), but no MCP installer. Antigravity has no hooks, so its tab writes a best-effort block into AGENTS.md.

Connected agents

The Connected agents card has one row per supported agent: Claude Code, Codex, and Cursor. Each row shows the agent name and a detection status.

• Detected means the app found the agent's folder (for example .claude, .codex, or .cursor) in the project or in your home folder.
• Not detected disables Install. Install or run the agent once so it creates its folder, then come back.

Install an agent

1. Select Install on the agent's row.
2. Read the Install Vibeless for <agent> dialog. It lists the main configuration files Vibeless will write or modify in your project. The table below has the full list.
3. Select Confirm.
4. Expand Last action on the row to see each file written and any warnings.
5. Restart the agent or open a new session so it loads the new configuration.

Once installed, the row shows Reinstall and Uninstall.

Files written per agent

An envelope file is a pre-written JSON file holding the text a hook injects. The hook reads it with a one-line node command.

Vibeless marks every entry it writes: a _vibeless_managed key in JSON files, # vibeless-managed-start and # vibeless-managed-end comments in the Codex TOML file, and a marked block in the Cursor rules file. In .claude/settings.json, Vibeless hook entries are recognized by a vibeless-hook marker inside their command. Uninstall uses these marks, so your own MCP servers, hooks, and rules stay as they are.

Reinstall and uninstall

Reinstall rewrites the agent's entries with the current port, token, and hook text.

Uninstall removes only the Vibeless entries from each file and the .gitignore lines Vibeless added. Everything you wrote stays. For a full audit of what Vibeless touches, see Docs/integrations-uninstall.md.

Rotate the token

Rotate the token if you think it has leaked.

1. Select Rotate token at the top of the card.
2. Read the Rotate project MCP token dialog. It names the installed agents that the new token affects.
3. Select Rotate token.
4. When the dialog lists the agents that need rewriting, select Reinstall all. Skip closes the dialog without reinstalling.
5. In each open agent session, reconnect the MCP server (for example /mcp reconnect in Claude Code).

The old token stops working at once. Any configuration that still holds it gets 401 invalid_project_token on its next call. If a reinstall fails, the dialog names the agent. Reinstall it from its row.

Generic MCP agents

For other agents, the final step of the setup wizard has a Generic MCP card with a snippet to copy. The snippet uses an older setup that starts vibeless-mcp-server as a command and reads the project token from VIBELESS_PROJECT_TOKEN. It holds a placeholder, not your token, and the app does not display the token anywhere. Use an automated agent where you can.

Hooks

The Hooks card lists hooks for this project, grouped by event. Each row has an on/off switch, the hook name, its command, a priority badge, its drift threshold and fail mode badges, and edit and delete buttons.

The 2 system hooks

Vibeless writes these for Claude Code and Codex when you install the agent. You do not create them on the Hooks card.

• Session start. Injects the session digest, a summary of the project's ground truth. See The session digest.
• Prompt submit. Named Governance Reminder in tool output. Injects a short reminder on every prompt. It says decisions and constraints bind advice as well as code, tells the agent to check the decision list once per session, and to orient new work with vibeless_declare_intent. It also tells the agent not to re-fetch context it already has, except after compaction or a change of topic.

Events for your own hooks

Hooks you write can use any of 7 events:

Vibeless translates each event to the agent's own name for it.

Create a hook with the guided builder

1. Select Add Hook. The New Hook panel opens in Guided mode.
2. Optionally type a name. If you leave it empty, Vibeless suggests one.
3. Step 1, What do you want to gate? Pick All file edits, Shell commands matching pattern, Specific MCP tools, End-of-turn, Session start, or Custom event. The shell and MCP choices ask for a pattern. Custom event switches to the free-form form.
4. Step 2, What action should it run? Pick Run a script and give an absolute path, or Run a shell command and type a one-line command. For session start, an Inject context from Vibeless option also appears. You do not need it: the system hooks already inject Vibeless context.
5. Step 3, How strict? Pick a Drift threshold (Low, Medium, or High) and a Fail mode (Open or Closed).
6. Select Create Hook.

Drift threshold and fail mode are saved with the hook and shown as badges in the list. The agent's configuration receives the event, the tool filter, and the command. Whether a hook can stop the agent depends on your command and on that agent's own hook rules.

Create or edit a hook in free-form

Select Free-form in the New Hook panel, or select the edit button on an existing hook. Editing always opens free-form. The form has Name, Trigger Event, Action, Tool Filter, Priority, Drift Threshold, and Fail Mode.

Install hooks into agents

Saving a hook stores it in Vibeless. It does not reach any agent until you install it.

1. Select Install hooks to .claude on the Hooks card. The button is disabled until the project has at least one hook.
2. In the Install Vibeless hooks dialog, pick an agent tab. The tab shows the file it will write to and any conflict warnings.
3. Turn Install Vibeless context-injection hook on to install it for that agent, or off to remove it.
4. Under User hooks, turn each of your hooks on or off for that agent. Each change rewrites the agent's configuration right away.
5. Select Show raw config to see and copy the merged file.

Stale path banner

A yellow banner reading Vibeless binary path is stale for N agents means a hook you installed from the Install Vibeless hooks dialog points at a file that no longer exists. A moved script or an older Vibeless install are the usual causes. The app checks Claude Code, Cursor, and Gemini configuration files each time you open the project.

Select Open Install Dialog and reinstall the hooks for the affected agent. If the hook runs your own script, edit the hook so its path is correct first. Dismissing the banner hides it until the next time you open the project.

Reports

The Reports card has one setting, Enable semi-formal certificates on Review. It is off by default.

When it is on and an agent moves a ticket to Review, Vibeless asks the agent to file a certificate with vibeless_attach_report. A certificate is a structured report that explains why the work meets the ticket. It has Definitions, Premises, Analysis, optional Edge Cases, Counterexample, and Formal Conclusion sections, plus a YES, NO, or PARTIAL answer.

Certificates appear in the Reports tab of the ticket's detail panel. Writing them uses more of the agent's tokens.

Agent-artifact paths

Agents leave scaffolding in a repository: plans, ticket notes, reports, settings, and whole git worktrees. The Agent-artifact paths card keeps that out of the Drift Log, the queue of file changes waiting for your review. The scanner, file watcher, git monitor, and manual sync all skip these paths.

The list has 3 parts:

To add a path, type it, select Add, then select Save.

Rules for extras:

• Paths are relative to the repository root, with no leading / and no .. segment.
• Each path can be at most 512 characters, and you can add at most 200.
• A path matches itself and everything under it, on folder boundaries. notes and notes/ both match notes/a.md, but not notes.md or src/notes/.
• A path containing * is a glob.
• A leading ./ is removed.
• Entries that would ignore every file, such as *, **, or *.*, are rejected.
• Matching ignores case. .claude/CLAUDE.md is always kept.

Saving deletes queued changes. When you save a changed list, Vibeless deletes the pending Drift Log changes that fall under it and reports how many it purged. Reviewed or dismissed changes are never touched.

Purge ignored paths runs the same deletion against the current list. Use it after a new worktree appears, because worktrees outside .worktrees/ are filtered from live changes but not from a manual sync. The confirm dialog shows how many changes will go, and purging is disabled when the count is 0. A purge cannot be undone.

Nothing on this card adds anything to the spec map. People maintain the map in the app.

The session digest

At the start of each Claude Code or Codex session, the session start hook injects a digest of the project. It contains, in order:

1. The project name and a line naming the MCP tools that hold the full detail.
2. A staleness warning, only when the spec map is stale. The map counts as stale when changes are waiting in the Drift Log, when it is 7 days old or more, or when it is empty.
3. The project goal.
4. The tech stack.
5. Constraints, the rules about what must not be touched.
6. The architecture overview, cut at 1,500 characters with a pointer to the full document.
7. Key decisions. A decision is a recorded choice and the reasoning behind it. Decisions that forbid something come first, then the newest. When space runs short, older decisions shrink to one line each and then to a count, with a pointer to the tool that lists them all.
8. A closing paragraph on how to work with Vibeless.

The digest is capped at 8,192 characters so the agent receives it in full. The goal and constraints are never shortened. The tech stack shows at most 12 lines, then a count of the rest. The active ticket is not included; agents fetch it through MCP.

Vibeless rebuilds the digest after every governance change (a new decision, for example), right after an install, and when the app starts. A session that is already running keeps the digest it started with.

How it connects to the rest of Vibeless

Installing Claude Code, Codex, or Cursor here clears the Agent not connected banner on the Dashboard Overview.

Rules and limits

Agents connected through MCP can:

• Read specs, decisions, constraints, phases, and tickets.
• Create tickets and change a ticket's status.
• Log decisions and attach reports.

Agents cannot:

• Edit a ticket's text or change a phase.
• Write constraints, non-goals, a decision's forbids list, or path globs on an existing project.
• Add anything to the spec map.

People make those changes in the app. The one exception is vibeless_create_project, which may seed starting constraints and non-goals on a brand-new project it creates.

If something looks wrong