The reasoning behind a design usually dies in browser tabs, chat history and notes nobody reopens. Design Harness keeps it alive. It is an open-source agent skill, MIT-licensed, for Claude Code, Codex and any other SKILL.md-compatible agent. You feed it sources such as papers, repos, posts and docs, and you say your judgments out loud. The agent files each source as a card, writes each judgment down as an idea card linked to its evidence, and assembles the final design only when you tell it to. Everything lives as plain Markdown in your repo, and one HTML canvas shows the whole board, so anyone can trace a decision back to the evidence behind it.
The rest of this article covers what it does, how the three layers fit together, how to install and use it, and when it is the wrong tool.
What is Design Harness and what problem does it solve?
Design Harness is a decision board for calls that have to stand on evidence. It closes the gap between a finished design document and the reasoning that produced it.
Most design work starts in a dozen places at once: a reference manager, a notes app, a whiteboard, a long chat with an AI model. The final document looks complete, but the path to it is gone. Six months later someone asks "why didn't we do X?" and nobody can answer without re-reading everything. Each existing tool keeps one piece of that path:
| Tool | What it keeps |
|---|---|
| Reference manager | The saved material |
| Notes app | Written observations |
| Whiteboard | Connections between ideas |
| Chat with an AI model | A transcript, until the context is gone |
| Design Harness | The path from source to idea to decision |
The design rests on one division of labor: the human adjudicates, the agent runs the errands. In the project's own words, agents execute well and judge poorly, and a wrong design costs the whole branch of code built on it. So the agent does the filing, grading, linking and assembling, and every judgment stays with you.
The project uses itself. Its own design was produced by running the method on roughly 80 sources about decision-making methods, and that workspace is the live demo canvas.
How does Design Harness turn sources and ideas into a design?
It keeps three layers of Markdown cards, each in its own folder, and moves information between them in one direction: evidence supports ideas, and ideas assemble into output.
Sources: one card per piece of evidence
Every paper, repository, blog post or document becomes one card under sources/<type>/. The agent files and grades each source, and anchors every claim to where it came from with an inline link. It names the type folders after what the sources are, such as papers or github, and adds new ones as needed. When two sources disagree, both go on the board as they are. The agent does not quietly pick the more convenient one.
Ideas: judgments only you make
An idea card holds a single judgment, written as one sentence. Only a human creates them. When you say what you have decided in conversation, the agent writes it down as a card and links it to the evidence and earlier cards it stands on. It never invents a judgment for you.
If a new idea repeats an old one, the two merge. If it contradicts an old one, the new card records a conflicts entry, the canvas draws a red edge between the two, and you decide. The losing card moves to ideas/archive/ with its reasons. It is never deleted, which is what makes "why didn't we do X?" answerable later.
Output: assembled on your word
The output is the deliverable, and its form comes from a target. file where you write the purpose and acceptance criteria. The first assembly happens only when you ask for it. After that, the output changes only on your command: the agent re-derives just the affected parts, shows a diff first for large changes, and mentions at most once that the output is a few ideas behind. If you edit the output by hand, that edit counts as a decision too, and the agent writes it back into the idea cards.
Three facts, and everything else derived
Only three structured facts are stored. References are inline links that point from a card to the evidence it stands on. Tags allow at most one per card; a card that needs two is two cards. Conflicts live on the newer card until you settle them. Backlinks, clusters, layout and indexes are all computed from those three, so there is nothing to keep in sync by hand.
How do I install Design Harness in Claude Code or Codex?
It installs as a plugin from a GitHub marketplace in both agents. Other SKILL.md-compatible agents can take the skill folder directly.
Claude Code:
/plugin marketplace add tigerless-labs/design-harness
/plugin install design-harness@design-harnessCodex (the CLI and the ChatGPT desktop app share one plugin system):
codex plugin marketplace add tigerless-labs/design-harnessThen install it from /plugins in the CLI, or from the desktop app's plugin directory.
Any other SKILL.md-compatible agent: clone the repository and copy the skill into your agent's skill directory.
git clone https://github.com/tigerless-labs/design-harness
cp -r design-harness/plugins/design-harness/skills/design-harness ~/.claude/skills/To update later in Claude Code, refresh the marketplace and then the plugin:
/plugin marketplace update design-harness
/plugin update design-harness@design-harnessIn Codex, run codex plugin marketplace upgrade and update from /plugins. There is no account, no API key and no server to run. The only cost is your agent's normal model usage.
What do I say to the agent once it's installed?
You talk to it in plain language, and two sentences cover most of the work:
file these papers onto the board
assemble the designA full pass looks like this:
- Drop material: the agent files and grades each source as a card
- Think out loud: your judgments land as idea cards linked to their evidence
- Say go: the ideas assemble into the output your target.md declares
- Ask for the canvas: the agent builds the board and gives you a clickable link
The first time it runs, the agent looks for a workspace. If it finds none, it asks where to create one; it never starts a new workspace silently, because a second workspace in the wrong place would split the record. The default location is docs/design-harness/, and a small registry at . remembers the choice. The bootstrap ends by asking for your target in your own words, and you can put that off until later.
A workspace looks like this:
<workspace>/
├── target.md your acceptance criteria; sets the output form
├── logs.md append-only change ledger
├── index.md entry point
├── sources/<type>/*.md evidence: one source, one card
├── ideas/*.md your judgments (archive/ holds the archived ones)
├── output/… the assembled deliverable
└── board/*.md free surface: comparison matrices, scratch reasoningboard/ is the one place with no rules. Use it for a comparison matrix or a page of scratch reasoning. Nothing in the other layers may point at it, though: when a board reaches a conclusion, that conclusion becomes an idea card.
If you need papers to feed it, Paper Radar finds papers linked to major AI labs and research institutes over any date range, which makes a good first batch of sources.
How do I share the canvas so others can see why the design is what it is?
Build the canvas into a single HTML file and commit it next to your workspace. Whoever opens that file gets the whole board, and every card is one click away from the evidence behind it.
python3 plugins/design-harness/skills/design-harness/scripts/build_canvas.py \
path/to/your-workspace -o docs
git add docs/canvas.htmlThe canvas has no server and no dependencies, and it holds no facts of its own. It is rebuilt from the Markdown whenever you ask, so it cannot drift from the record. Put it at docs/canvas. and GitHub Pages can serve it as a link with no workflow to set up, which is how the project's own demo board is published.
Five visual styles ship with it, and you can switch between them live from the toolbar. Pin & Paper is the default. Below is the same workspace in each one:
How is Design Harness different from asking an AI to write the design doc?
An AI asked to "write a design for this" decides for you and gives you a document with no trail behind it. Design Harness reverses both: you decide, and every line of the result points back to why.
| Dimension | Design Harness | Asking an AI model directly | Writing it by hand |
|---|---|---|---|
| Who makes the calls | You, every one | The model, implicitly | You |
| Link from claim to evidence | Inline link on every card | Rarely, and not checkable | Only if you keep it up |
| Conflicting evidence | Shown as a red edge for you to settle | Usually smoothed over | Up to your memory |
| Rejected options | Archived with reasons | Gone with the chat | Usually lost |
| Updating the design | Re-derives only what changed, on your word | Regenerates the whole document | Manual edits everywhere |
| Storage | Plain Markdown in your repo | A chat transcript | Docs or slides |
The tool around a model changes what the model is good for. We saw the same thing measured another way when the same model scored 42 or 78 depending on its harness. Design Harness applies that idea to design work: it puts the agent's effort into the errands it does well and keeps it out of the judgment it does badly.
When is Design Harness the wrong tool?
When the decision is small, when you want the AI to generate options, or when you need a live collaborative whiteboard, something else will serve you better.
Small or obvious decisions. Filing sources and writing idea cards takes effort. If the answer is clear after reading two pages, a short note in your pull request is enough.
You want ideas generated for you. Design Harness will not brainstorm on your behalf or pick a side in a conflict. If you want a model to propose architectures, ask it directly, then bring the proposals you believe back to the board as your own judgments.
Real-time co-editing. The canvas is a read-only projection rebuilt from Markdown, not a shared whiteboard. A team sketching together live is better off in a whiteboard app, with the conclusions filed afterwards.
No agent in your workflow. It is a skill, not a standalone app. It needs Claude Code, Codex or another SKILL.md-compatible agent, plus a little command-line setup.
Token budget. Reading and grading a stack of papers is heavy model work. If you want to see what that costs request by request, cost-xray shows what your agent sends to the API and what each part costs; our guide on reading what Claude Code sends to the API walks through the other ways to check.
It is also not a memory layer. Design Harness records the reasoning for one design. If you want your agent to remember what it learned across all its sessions, agent-memory does that job, and AutoHarness turns your real coding sessions into reusable skills.
Conclusion
Design Harness turns scattered reading and half-formed ideas into a design you can defend. Sources become cards, your judgments become linked ideas, the output assembles only on your word, and a single HTML canvas lets anyone trace each decision to its evidence.
A simple rule for when to use it: if someone will later ask why the design looks the way it does, and the honest answer today would be "it was in a chat somewhere", the decision is worth putting on a board.
The free next step is to open the live canvas and click any idea card to follow it back to its sources. If that is the trail you want for your own decisions, install the plugin, point it at the papers you already have open, and say "file these papers onto the board". The other open-source tools we build are on Tigerless Labs.
FAQ
Is Design Harness free to use?
Yes. Design Harness is open source under the MIT license, and the code is on GitHub. There is no account, API key or server. The only cost is the model usage of the agent you already run, such as Claude Code or Codex.
Does Design Harness work with agents other than Claude Code?
Yes. It installs as a plugin in Codex, where the CLI and the ChatGPT desktop app share one plugin system, with codex plugin marketplace add tigerless-labs/design-harness. Any other agent that reads the SKILL.md format can use it by copying the skill folder into that agent's skill directory.
Will the agent ever make a design decision for me?
No. Only a human creates idea cards. The agent writes down judgments you voice, links them to evidence, merges duplicates and flags conflicts as red edges, but it does not pick a side. The output also changes only when you tell it to sync.
Where is the data stored, and does it need a database?
Everything is plain Markdown in folders inside your repository: sources/, ideas/, output/ and an optional board/. There is no database. The canvas is a single HTML file rebuilt from that Markdown, so you can version, diff and review the whole record with Git.
Can the output be something other than a system design?
Yes. The output's form comes from the target. you write. System design is the first form in the skill's library, and the project describes other uses such as the design of a skill, a video script or the structure of an article. Anything that has to stand on traceable evidence fits.
