MCP & Hooks

The Vibeless desktop app runs a local MCP server over HTTP on 127.0.0.1. Your editor calls it directly — everything runs on your machine, no LLM round-trips, no credits consumed by tool calls.

For Claude Code, Codex, and Cursor, setup is fully automated: the in-app installer writes the MCP config, the per-project auth token, and the default context hook for you. There is no CLI to install, no binary to put on PATH, and no token to copy.

One-click install (Claude Code, Codex, Cursor)

1. Open your project in Vibeless.
2. Go to Project Settings → Connected Agents.
3. Find your agent's row. If detection shows Detected, the Install button is enabled.
4. Click Install. The confirm dialog lists exactly which files Vibeless will create or modify.
5. Click Confirm. An install report below the row shows what was written.
6. Restart your editor (or open a new session) to pick up the new config.

What gets written

| Agent | Files | |---|---| | Claude Code | <project>/.mcp.json, hook entry in <project>/.claude/settings.json, hook envelope in <project>/.vibeless/hooks/ | | Codex | <project>/.codex/config.toml (MCP entry + hooks feature flag), <project>/.codex/hooks.json, hook envelope in <project>/.vibeless/hooks/ | | Cursor | <project>/.cursor/mcp.json, <project>/.cursor/rules/vibeless.md |

The MCP entry is an HTTP transport pointing at the app's local server. For Claude Code (.mcp.json):

{
  "mcpServers": {
    "vibeless": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <project-token>" }
    }
  }
}

For Codex (.codex/config.toml):

[features]
codex_hooks = true

[mcp_servers.vibeless]
url = "http://127.0.0.1:<port>/mcp"
http_headers = { Authorization = "Bearer <project-token>" }

Cursor's .cursor/mcp.json uses the same url + headers shape (without the "type" field). In every case the installer fills in the real port and token — the snippets above are shown so you can audit what lands in your repo, not something you copy by hand.

Everything Vibeless writes is identifiable as Vibeless-owned — marker-wrapped, except Claude Code's .claude/settings.json hook entries, which are recognized by their .vibeless/hooks/ command path — so Uninstall (same row) removes only Vibeless-owned entries and leaves your own MCP servers, hooks, and rules untouched. Vibeless also adds the written files to your .gitignore where appropriate and removes those lines on uninstall.

Tokens and the local port

Each project has its own auto-generated MCP token; it authenticates your editor's calls and scopes them to that project. The local port is assigned by the app. You never manage either one:

• On every app start, Vibeless re-checks all installed agent configs and silently repairs a changed port or token (self-healing resync).
• Rotate token in Connected Agents regenerates the project's token — the dialog lists which agents need reinstalling and offers one-click Reinstall all. Live agent sessions must reconnect after a rotation.
• If you move or reinstall the Vibeless app, click Reinstall in Connected Agents to rewrite the configs in one pass.

Other MCP-aware editors (manual setup)

Editors without an automated installer can use the bundled vibeless-mcp-server bridge binary over stdio. Select Generic MCP in the app to copy the base snippet:

{
  "mcpServers": {
    "vibeless": {
      "command": "<absolute path to vibeless-mcp-server>",
      "env": {
        "VIBELESS_PROJECT_TOKEN": "<project-token>"
      }
    }
  }
}

VIBELESS_PROJECT_TOKEN is the only env var required. Fill in the two placeholders:

• Binary path — the binary ships inside the app install, in the binaries/ folder next to the app executable: %LOCALAPPDATA%\Vibeless\binaries\vibeless-mcp-server.exe on Windows, /Applications/Vibeless.app/Contents/MacOS/binaries/vibeless-mcp-server on macOS. Use the full absolute path in command.
• Project token — with the Vibeless app running, open ~/.vibeless/manifest.json and copy the token from your project's entry. The manifest is the app's runtime state file; the bridge binary reads it to find the local server, so if it exists, the token in it is current. Rotating the token in the app means updating it here too.

The bridge needs the Vibeless app running; if the app is closed, tool calls report that Vibeless is unavailable and recover automatically once you reopen it — no editor restart needed.

Cross-filesystem setups (WSL, sandboxed installs): if your editor runs in a different filesystem namespace than the app (e.g. Vibeless on Windows, Claude Code in WSL), the bridge won't find ~/.vibeless/manifest.json on its own. Add "VIBELESS_MANIFEST_PATH": "/mnt/c/Users/<you>/.vibeless/manifest.json" (adjust to your setup) to the env block.

Gemini CLI and Antigravity are not supported by the installer yet — their integrations are planned for a later release. Any editor that speaks MCP can connect through the Generic MCP path above in the meantime.

Hooks

Hooks make your editor consult Vibeless automatically on key events instead of relying on the agent to remember. There is no separate hook binary: at install time Vibeless writes a small pre-rendered envelope file into <project>/.vibeless/hooks/ containing the "consult Vibeless first" instruction, and configures the agent's hook to print that file into the agent's context when the event fires.

By default the installer ships one hook — user_prompt_submit — which injects fresh project context every time you submit a prompt. On Cursor, which routes agent guidance through rules files, the .cursor/rules/vibeless.md file plays the same role; rules adherence is best-effort, so hook-style behaviors are less deterministic on Cursor than on Claude Code or Codex. That's a platform limitation, and the rules file itself documents it.

Custom hooks

The Hook Editor in the app exposes the full canonical event taxonomy for hooks you author yourself, translated to each editor's native event names on install:

| Canonical event | Fires | |---|---| | session_start | when an agent session begins | | user_prompt_submit | when you submit a prompt, before the agent plans | | pre_tool_use | before the agent runs a tool | | post_tool_use | after a tool completes | | stop | at end of turn (can block the stop) | | pre_compact | before the context window is compacted | | pre_shell_execution | before a shell command runs |

The Hook Editor shows per-editor support, best practices, and caveats for each event as you author.

Verifying the connection

After installing, ask your agent:

Call vibeless_get_project_context and tell me what project I have open.

If the response describes your active Vibeless project, the MCP server is connected and the tools are available.

Available tools (overview)

See the MCP Tool Reference for details on every tool. All tools execute locally — none make external LLM calls or consume credits.

| Tool | Purpose | |------|---------| | vibeless_declare_intent | Start here — declares the task and returns the project map plus suggested starting nodes | | vibeless_get_node | Fetch a context node: outline, a single section, or a chunk of a large document | | vibeless_spec_neighbors | Neighboring nodes of a spec/context node in the graph | | vibeless_get_project_context | Project info, active phase, constraints, enforcement coverage | | vibeless_get_architecture | The project's architecture document | | vibeless_get_phase_spec | Phase spec and tasks | | vibeless_get_task_spec | Single task with merged constraints | | vibeless_search_specs | Full-text search across project specs | | vibeless_get_version_history | Recent version-history events for an entity | | vibeless_check_constraint | Constraint and prior-decision lookup | | vibeless_list_constraints | Read-only constraint list | | vibeless_log_decision | Persist an agent decision | | vibeless_list_decisions | Decision log, newest first | | vibeless_run_drift_check | Deterministic drift report | | vibeless_list_open_tasks | Tasks in pending / in-progress / blocked | | vibeless_create_task | Create a task at the bottom of a phase's Backlog (permanent record) | | vibeless_update_task_status | Update a task and get the next pending task | | vibeless_add_task_comment | Append a permanent progress comment to a task | | vibeless_get_active_ticket / vibeless_set_active_ticket | Read or set the ticket the agent is working | | vibeless_attach_report | File a completion certificate for a task (required by task-status updates when post-task reports are enabled) | | vibeless_get_hooks | Active hooks for a trigger event | | vibeless_get_context | Resolved governance context for a scope (legacy — prefer declare_intent + get_node) | | vibeless_get_adapter_info | Active adapter configuration | | vibeless_topology_summary | Code graph node/edge counts | | vibeless_topology_query | Filter graph nodes and edges | | vibeless_create_project | Create a new Vibeless project (respects your plan's project limit) | | vibeless_get_workspace_context | Workspace-level context across linked projects | | vibeless_link_projects | Link two projects in a workspace | | vibeless_get_linked_project_context | Context from a linked project | | vibeless_check_cross_project_constraint | Constraint lookup across linked projects |