Two checks, then four steps in the order you run them. Whatever you launch from your agent lands in the interface: that is where you read the result.
Part 1
Check your installation
Two checks, once.
1. Lyriks runs correctly
In Lyriks, open the Versions page: your initials, Lyriks settings, Account settings, Versions. Green is what you want, and grey is fine: on a Community install, Lyriks-back and the DPO engine read “Not configured”, because they are Enterprise components. The check passes when no card reads “Unreachable”.
2. Your AI agent can act on Lyriks
Lyriks exposes an MCP server at the address of your installation, the one you open in the browser, followed by /mcp. Add it once to the agent you already code with.
$ claude mcp add --scope user --transport http lyriks https://<your-installation>/mcp
Any other client: an HTTP MCP server named lyriks at that address, then restart the client. Or let your agent do it itself:
I want to connect Lyriks to this conversation. Lyriks exposes an MCP server
at this address: https://<your-installation>/mcp
Add the connector yourself if you can. Otherwise tell me exactly where to
click or what to paste in the application I am using right now, and whether
it has to be restarted. Then list the Lyriks tools you can see.
If the address does not answer, give me the exact error rather than a guess.
Then check that it can really act on Lyriks:
Create a project named "MCP Test" in Lyriks, then list the projects of the
portfolio and tell me whether "MCP Test" is in it.
The agent confirms the creation, and the project appears in your portfolio. Delete it once you have seen it.
Part 2
Working with Lyriks
Four steps, in the order you run them. Whatever you launch from your agent lands in the interface: that is always where you read the result. Each one carries the prompt its demo types: what sits in braces is yours to fill, starting with {project}, the name your project has in Lyriks.
1
Get your specification out of your codebase
Lyriks does not read your repository: your coding agent does, from inside the repo, and writes the specification into Lyriks through the connector. You have nothing to write.
With the help of the Lyriks MCP, ingest this entire codebase into the Lyriks
project {project}.
In the portfolio, New project, then From a codebase.Lyriks hands you one line to paste, with the project already named in it.
Open your agent inside the repository and paste that line.(Claude Code, Codex, Gemini CLI, Copilot) On the first run it asks you to sign in to Lyriks in your browser.
Come back to the project.The sections fill in as the agent authors them, and it asks you only for the decisions your sources cannot settle. The wait is your agent's, not a job running somewhere in Lyriks.
You can finally read what your software does, and why.Its intents, its business rules, its constraints, and the points the code alone could not settle.
The line stays on the project's Kickoff page, one click from Foundation, so you can hand it to another agent later.
2
Read what it found in your product
The project opens on Foundation, and the left column holds the rest: Users & Permissions, Features, Experience, Data & Architecture, Glossary. Evolution is not one of them: it is a tab inside Features, beside the tree it changes. Open a feature to see its intent, its rules and what depends on it.
Using the Lyriks MCP, tell me what the specification of {project} says about
the coherence score: what it measures, and where to start raising it.
Read the scores at the foot of the column.Coherence is how free of contradictions the specification is, Coverage what is present, Build readiness whether there is enough depth to build on.
Click a score to open the Control Center.Every issue is listed there, the worst first, each with the place to fix it.
Take the contradictions before the gaps.A contradiction distorts everything that rests on it; a gap only limits what is covered.
You stop digging through the code to find out why a rule exists.The answer, and everything that depends on it, is a few clicks away.
3
Ask for a change, and read what it moves
A change stays apart from the specification until it is built and verified. Lyriks calls it an evolution, and it is made in features that already exist: whatever new it needs shows up in the impact report, never as a feature you create by hand.
Features, Evolution tab, New evolution.Say the change in one sentence, then pick the features it touches.
Sign the values.Five questions per touched feature: objective, problem, value, measurable effect, acceptance criteria. The assistant proposes an answer with its sources; you accept it, reword it or refuse it, and accepting writes it on the feature.
Compute the impact report.Three readings, never merged into one: if we add it, if we change it, if we remove it. Removing does not break what adding breaks.
You know what the change costs before a line of code is written.The rows marked direct are the work itself. The knock-ons have nothing to edit, they merely rest on what changes, so they have to be re-read, re-run or re-approved: that is what breaks quietly.
In the Lyriks project {project}, open an evolution for this change: {change}.
Tell me which features it touches and what it will ask me to sign.
Compute the impact of the evolution {name} in the Lyriks project {project},
and give me the three readings rather than one number.
4
Build it, then verify it
Here the specification is the authority and the model executes. That is what makes models interchangeable, and what often lets a more modest one do the job: most of an LLM’s mistakes come from having to guess the intent.
Freeze the specification into a version,then ask your agent to implement the evolution.
It stops and askswhenever the evolution left a decision open, instead of improvising one.
Verify: the code against the frozen specification.One line per expectation, each one yours to decide. A line you refuse comes with a brief you copy straight back to the agent.
What ships is what you signed.The gap between the two is a list you read, not a surprise in production.
Implement the evolution {name} of the project {project} in Lyriks, strictly
respecting the values signed on it. If a decision is not settled there, stop
and ask me rather than choosing.
Part 3
Any question?
Where do I start?
The two checks above, then point your agent at an existing repository to write its specification. It is the first visible result, it asks you to write nothing, and the rest follows from it.
A card on the Versions page is not green
On a Community install, two cards read “Not configured”, and that is correct: Lyriks-back and the DPO engine are Enterprise components. “Recorded at install” and “Unknown” are grey statuses that mean the same on both editions. “Unreachable” is the one to report: tell us which card it is at support@lyriks.io.
My agent does not see Lyriks, or every write is refused
No Lyriks tool at all: check that the address is the one of your installation followed by /mcp, then restart the client, since most read their configuration only at startup.
The tools are there, but every write is refused: by default, Lyriks blocks what an LLM proposes. Allow it for the workspace in Settings, AI suggestions, then run the test again.
My activation key is not accepted
Check first that you pasted the whole key, line breaks included. On an installation without network access, use the offline activation: the verification happens locally. If you never received the key, write to support@lyriks.io and mention the address you requested it with.
Does my code leave my machine?
No. Lyriks is installed on your side and never calls an AI service itself: there is no AI key to give it. Everything an AI does here goes through your own agent, over the connector, and only if you allow it.
Which LLM should I use? Am I locked in?
The one you prefer, as long as your client speaks MCP. The intent is carried by the specification, not by the model, so you can change models without losing anything.
My coherence score is low, where do I start?
Open the Control Center: the issues are listed worst first, each with the place to fix it. Take the contradictions before the gaps.
I want to talk to someone
Ask on our Discord (link below the questions) or write to support@lyriks.io with three things: your Lyriks version, the exact error message if there is one, and what you were trying to do.