What Vibeless is
The mental model: specs, phases, tickets, decisions, drift, and how agents are kept on track.
Last updated:
On this page
Vibeless keeps the governing record of a software project and hands it to the AI coding agents that work on it. You use it to set what a project is for, what it must and must not do, and what work comes next, so agents build to that record instead of drifting away from it.
The problem it solves
A coding agent starts each session with no memory of earlier sessions. It does not know which libraries you ruled out, which features are out of scope, or which ticket it should be on. Over a long project the code drifts from the plan, one reasonable-looking change at a time.
Vibeless is not an AI and does not write code. It holds the project's ground truth outside the repository: the goal, the spec, the architecture, the constraints, the non-goals, the phases, the tickets, and the decisions. Agents read that record through MCP (the Model Context Protocol, the standard way agents call external tools) and through hooks that Vibeless installs into the agent's own configuration.
The core objects
Everything in Vibeless belongs to a project. A project is one codebase and its governing record.
| Object | What it is |
|---|---|
| Spec | The project's description, goal statement, tech stack, constraints, and non-goals. A constraint is a rule the code must follow. A non-goal is something the project deliberately does not do. |
| Architecture | A written architecture document for the project, edited next to the spec. |
| Phase | A stage of work with its own scope. A phase can carry path globs, which name the files that belong to it. Several phases can be active at once. |
| Ticket | One unit of work inside a phase, with a status that moves across a board. |
| Active ticket | The one ticket pinned as current for the project. You or an agent can pin it. |
| Decision | A recorded choice with its rationale and the alternatives considered. A decision can list dependencies it forbids, and the drift check looks for them. |
| Context node | A rule, spec, or standard attached to the project, a domain, or a feature. Context nodes and their file mappings form the spec map that agents read. |
| Drift | A gap between what the record says and what the code does. |
| Version history | An append-only log of every change to the record, kept separately from git. |
Drift shows up in 2 ways. A file watcher and a git monitor record each change in the repository as a change event and classify it, and the events that need a look land in the Drift Log. A drift check is a separate, on-demand report that an agent runs. It compares the code against the tech stack, the constraints, the non-goals, the path globs of the lowest-numbered active phase, and the forbidden dependencies. Its findings appear in the agent's report, not in the Drift Log.
Nothing a scan or the file watcher finds is added to the spec map on its own. The map changes only when a person edits it in the app.
The pieces that run
The desktop app. Vibeless is a desktop app built on Tauri. Its databases are SQLite files on your machine: a registry in ~/.vibeless/ and the project databases in the app's data folder under your user profile. Each connected repository also gets a .vibeless/ folder, which holds the hook files the agent installer writes.
The MCP server. The app starts a bundled MCP server in the background. It listens on your own machine at http://127.0.0.1:<port>/mcp. When you install Vibeless into Claude Code, Codex, or Cursor, the installer writes that address into the agent's config, with a per-project token in an Authorization: Bearer header. The token tells the server which project the agent belongs to. The server matches it against ~/.vibeless/manifest.json, a file the app keeps up to date. You never paste a port or a project ID.
Hooks. For Claude Code and Codex, the installer adds 2 hooks to the agent's configuration by default. The SessionStart hook injects a digest of the project's ground truth at the start of every session: the goal, tech stack, constraints, architecture overview, and decisions, plus a staleness line when the spec map may be behind. The digest does not include the active ticket or the current phase; the agent fetches those through MCP. The user-prompt-submit hook adds a reminder to every prompt: consult the Vibeless MCP and honor binding decisions. Cursor has no equivalent hook system, so Vibeless writes a rules file that asks the agent to call the same tools.
The Vibeless cloud service. You sign in to the app with a Vibeless account. The cloud service handles sign-in, plans, and the LLM features, which are billed in credits. It also carries team sync for projects shared with an organization.
Core features run on your machine and do not need a paid plan. These include editing the spec, phases, tickets, decisions, and context nodes, the hooks, the MCP server, the Drift Log and drift check, version history, and keyword search. LLM features, such as Vibe Coder, need a paid plan. The free plan has no LLM features.
Hooks as the floor, MCP as the ceiling
Hooks are the floor. They fire on the agent's own events, so the ground-truth digest reaches the agent whether or not the agent asks for it.
MCP is the ceiling. Through the MCP tools, an agent can go well past the digest:
- Read the spec, the architecture, phase and ticket specs, the constraints, and the full decision log.
- Search the spec and fetch the context that applies to the files it is about to touch.
- Declare what it intends to work on, then run a drift check against the record.
- Create tickets, change a ticket's status, and pin the active ticket.
- Log decisions, add comments to tickets, and attach reports.
Some parts of the record belong to people only. An agent never edits a ticket's text and never creates, edits, or moves a phase. An agent never changes an existing project's constraints, non-goals, the dependencies a decision forbids, path globs, or the spec map. You change those in the app. The one exception is vibeless_create_project, which can seed starting constraints and non-goals on a brand-new project it creates.
The full tool list is in MCP tools reference.
A tour of the sidebar
The sidebar lists the main panels in this order. Hover over an item to see its shortcut.
| Item | Shortcut | What it is for |
|---|---|---|
| Dashboard | Ctrl+1 | The project overview, with tabs for connected agents, the team, enforcement, and settings. |
| Spec Editor | Ctrl+2 | The spec fields and, on a second tab, the architecture document. |
| Phase Planner | Ctrl+3 | Phases, their order, their status, and their path globs. |
| Tickets | Ctrl+4 | The ticket board, where you create, move, and pin tickets. |
| Logs | Ctrl+5 | Decisions, Version History, and the Drift Log, plus a Changelog tab on team projects. |
| Context Editor | Ctrl+6 | Context nodes and file mappings, which make up the spec map. |
| Topology | Ctrl+7 | A graph of the code's structure that Vibeless extracts from your files. |
| Vibe Coder | Ctrl+V | A guided chat that turns an idea or an existing codebase into a structured project. Needs a paid plan. |
| Organization | None | The organization, its teams, and shared projects. Shown only when your account belongs to an organization. |
| Account | Ctrl+0 | Your account, plan, credit usage, and projects. |
| Search | Ctrl+/ | Keyword search across the record. Ctrl+K also opens it. |
The Logs item shows a badge with the number of change events waiting for review that are classified as drift or unknown. Click the badge to open the Drift Log.
Some tasks start outside the sidebar:
- Importing an existing project covers Import Project, which you open from the new-project dialog (Ctrl+N) or from the Dashboard.
- Connecting agents covers installing Vibeless into Claude Code, Codex, Cursor, and other agents.
- Workspaces and linked projects covers grouping related projects. The app cannot add a project to a workspace, and a new project never joins one.
- The glossary defines every Vibeless term.
A typical loop
- You write the spec and the architecture, plan phases, and add tickets.
- You connect your agent from the Agents tab on the Dashboard.
- The agent starts a session and receives the digest through the SessionStart hook.
- The agent pins a ticket, declares what it will touch, and starts work.
- The agent logs the decisions it makes and moves the ticket's status forward.
- You review the Drift Log, then accept, flag, or dismiss each change, and update the record where the plan itself has moved.
Where your data lives
Your project record stays on your machine, in the local SQLite databases described above.
These things leave your machine:
- Sign-in, plan, and credit usage, which go to the Vibeless cloud service.
- The inputs to an LLM feature when you use one, such as a Vibe Coder turn. These go through the Vibeless cloud service to the model provider.
- Sync operations for projects you share with an organization. Sync is encrypted at rest and in transit under a per-organization key.
- Anonymous crash reports, unless you turn them off under Account. They contain no source code or prompts.
- The update check. The app checks for updates on its own and shows a banner. It never installs an update until you choose to.