Open source
Groundwork for Claude Code
Your product evidence, in your repo, written by your own agent.
groundwork-mcp 0.3.0 · Apache-2.0
Evidence that lives next to your code
An MCP server and CLI. Claude Code, or any MCP agent, keeps customer insights, hypotheses, experiments, findings and requirements as linked Markdown files in a groundwork/ folder in your repo. Every requirement traces back to the findings, experiments and customer quotes behind it.
Why files in your repo
No account, no API keys, no server
Your own agent does the thinking. Groundwork checks the data, keeps links valid and computes experiment verdicts. An experiment is validated only if the primary metric hits its target and no guardrail is breached.
Plain files
Readable, diffable and reviewable in pull requests. Kept as long as you like.
Traceability
Ask “why are we building this?” and get the full evidence chain. Or check it in CI with groundwork validate.
Quickstart
In a project folder, add the MCP server to Claude Code.
claude mcp add groundwork -- npx -y groundwork-mcp
Or install it as a Claude Code plugin. That adds the MCP server plus a skill.
/plugin marketplace add IdeatorlabsAB/groundwork /plugin install groundwork@groundwork
Other agents
Groundwork works with any MCP agent. The server command is npx -y groundwork-mcp.
Codex
codex mcp add groundwork -- npx -y groundwork-mcp
[mcp_servers.groundwork] command = "npx" args = ["-y", "groundwork-mcp"]
To teach Codex when to use it, copy the skill into your repo.
mkdir -p .agents/skills/groundwork curl -fsSL -o .agents/skills/groundwork/SKILL.md \ https://raw.githubusercontent.com/IdeatorlabsAB/groundwork/main/skills/groundwork/SKILL.md
Start codex in your project folder, so Groundwork finds the project.
Then talk to your agent normally
- “Here are my notes from three customer interviews. Log the pains as insights.”
- “Why are we building the guided import?”
Files look like groundwork/insights/INS-0001-setup-takes-too-long.md
From a customer's words to a requirement
Insight, hypothesis, experiment, finding, requirement. Each one links to the one before.
- Insight“I gave up after 20 minutes”
- HypothesisGuided import will lift activation
- ExperimentPilot with 10 accounts, validated
- FindingActivation 61% vs 38%
- RequirementGuided CSV import
Run groundwork trace REQ-0002 to see a requirement's evidence tree in your terminal.
The CLI and the MCP tools
CLI
Run with npx -p groundwork-mcp groundwork <command>, or install it with npm i -g groundwork-mcp.
- groundwork init
- Create groundwork/config.yml
- groundwork validate
- Check every item and link. Exits 1 on errors, for CI
- groundwork trace REQ-0002
- Show the evidence chain behind an item
- groundwork list [kind]
- List items, optionally only one kind
- groundwork import --to <web app URL>
- Move a project into the web app. Add
--dry-runto check first - groundwork mcp
- Run the MCP server (same as
groundwork-mcp)
MCP tools
Read
- get_workspace
- search_items
- get_item
Write
- add_insights
- add_hypotheses
- add_experiment
- add_findings
- add_requirements
- update_item
- link_items
- delete_item
- add_product_areas
- add_products
Lifecycle
- start_experiment
- record_experiment_results
- submit_requirement_for_approval
- approve_requirement
- send_back_requirement
- obsolete_requirement
Privacy
Agents are told to record a role, like “Finance manager”, and an optional reference, like “P07”. Never names or contact details. Files usually end up in git, so check quotes before you commit them, and keep the repo private if they're sensitive.
When your team wants more
The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync, for people who don't live in a terminal.
The open-source project is and stays open source. To move a project into the web app:
Create a token
Sign in to the web app and open the workspace you want to import into. Go to Settings → Connect an agent and create a token. The token belongs to that workspace, so that's where the import goes. Copy it straight away: it's shown only once, and starts with
gw_. You need to be an editor or owner.Check what would be imported
In your project folder, set the token and do a dry run. It shows which workspace the items will go to and how many are new. Nothing is saved.
Dry runexport GROUNDWORK_TOKEN=gw_… npx -p groundwork-mcp groundwork import \ --to https://groundwork.ideatorlabs.com --dry-run
Import
Run it in the same terminal, so the token is still set.
Move the project into the web appnpx -p groundwork-mcp groundwork import \ --to https://groundwork.ideatorlabs.com
Items keep their links and their original ids, like INS-0001. Running it again skips items already there; add --overwrite to replace them. Afterwards groundwork/config.yml says migrated:, so local tools only read the files, and the command prints how to point Claude Code or Codex at the web app.
Contribute
Issues and pull requests are welcome.