With an agent

Your AI agent drives Effortless through its MCP verbs: it reads the project state, creates, updates, checks. You decide, the agent executes. The app shows the same project, at the same time: everything the agent does shows on screen (see the app guide).

You talk to your agent in plain language. Each page of this guide starts from what you ask, then says what the agent does, what you get, and what happens when a call is refused.

Compatibility

Effortless does not target one particular agent. Today, agents built on frontier models (LLMs) are the best placed to use it — Claude Code, Codex or Antigravity for example. Integration with opencode is in progress; depending on the model used, similar behavior is not guaranteed.

Working at your best: the agent opened at the project root

The best Effortless experience comes from a command-line agent — Claude Code, Codex or Antigravity, for example — whose session is opened at the project root, that is, in the folder that contains effortless.json and .effortless/.

Why the root:

• the Effortless MCP server recognizes the project from the folder where the session was opened. Opened anywhere else, it finds no project, and its verbs say so when they refuse;
• the root is where AGENTS.md and CLAUDE.md live, which the agent reads at startup to learn the verbs and the method;
• the agent works directly in the project's code, where its changes and commits go.

In practice, in a terminal:

cd ~/Projects/my-project   # the folder that contains effortless.json
claude                     # or codex, or your agent's command

Then talk to it: "Where does the project stand?" or "Start a story for the quote form". Keep the Effortless app open alongside: you see, live, what the agent does.

Other ways of working remain comfortable:

• the VS Code integrated terminal (or another editor's): open the project folder (File › Open Folder), then a new terminal — it already opens at the root. Run your agent there;
• your agent's extension or desktop client, as long as the session targets the project folder.

If the agent answers that no Effortless project is found, the session was almost always not opened at the root: close it, move into the project folder, and start it again.

Connect an agent

Two routes, which do the same job:

• From the app: Preferences, MCP & Skills category. Select the detected assistants, then Deploy (see Profile and preferences).
• Through the agent: effortless_deploy. With no parameter, it targets every client detected on the machine.

Deployment installs:

• the Effortless MCP server configuration in each detected client;
• a global Effortless guide, between markers, in the instruction files of the targeted agents (~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md): the rest of those files is left untouched;
• for Claude Code, an Effortless status bar (~/.claude/effortless/statusline.mjs). If you already have your own status bar, it is kept: the deployment report gives you the line to set to adopt Effortless's.

After a deployment, restart or reconnect the server in your agent so it sees the verbs.

Inside a project

effortless_init and effortless_features (with write_doc: true) write two files at the project root, between markers, leaving the rest alone:

• AGENTS.md: the full registry of verbs, derived from the engine. This is what the agent reads to know what to call.
• CLAUDE.md: it imports AGENTS.md (the @AGENTS.md line), for agents that read that file.

Do not edit them between the markers: the section is regenerated.

Work modes

The mode is set per project, in Project settings (see the screen) or by asking the agent (effortless_mode_set).

Mode	What the agent may do
Full	Moves forward autonomously, with no intermediate validation.
Semi-auto	Proposes, and you validate the key milestones. Execution tools are disabled: the team loop, running a release, public promotion. Moving the code into codebase/<stack>/ does not run either.
Tutored	Pedagogical step by step: each step is explained and confirmed.

You stay in control

Outgoing or irreversible actions (commit, push, tag, release, publication) are only done by the agent after your explicit agreement.

When a call is refused, the refusal says two things: a code (the cause) and an act (what to do so the same call succeeds: another verb, or an argument to fix). Your agent uses it directly; each journey page lists the real refusals of its verbs.

The journeys

Page	For
Get started	Create a project, take over an existing one, deploy.
Take stock	Know where the project stands and what awaits you.
Frame	Set decisions, questions and framing.
Steer	Epics, stories, tasks and phases.
Evolutions	Note, order and graduate ideas.
Standards	Development standards, shared source, amendments.
Code	Stacks, models, modules, drift.
Quality	Measure, validate, repair.
Deliver	Plan and run a release.
Documentation	Project documents, search, user documentation.
Team loop	Have analyst, developer and QA work in relay.

Reference

Every verb, its parameters and scope: MCP reference.