Working with an AI agent, you can try a dozen things a day. By the time you write the paper, only the one that worked is left. The failed attempts and the corrected numbers are scattered across chat logs.
Duetkifu is an open-source (MIT) tool I built for exactly this. It keeps the research record you and your AI agent build together: every move, dead ends included, and where each number comes from. It works with Claude Code, Codex, Gemini CLI, Cursor, or any AI agent that can edit JSON files.
GitHub: https://github.com/Ashur5457/duetkifu | Tutorial: docs/tutorial.md | Summary for LLMs: llms.txt
Why record dead ends?
A paper shows the path that worked. The rest, such as failed attempts, numbers that were later corrected and clues noticed too late, ends up in chat logs, slides and memory, and then it is gone. The faster the agent tries things, the faster this hidden part grows, and nobody can keep up by writing it down by hand.
What Duetkifu does
- Every attempt is a "move". Each move records which move it follows, why it was made, what came of it and, for a dead end, why it ended.
- Dead ends are results. A failed move needs a reason and a cause: the idea was wrong, the data cannot be trusted (so the path was never really tested), the analysis method, or the cost. The next person, or the next agent, can then tell a closed path from an untested one.
- Every number has a source. It is recomputed from raw files by recorded scripts, or taken from a named file with a SHA-256 fingerprint, or marked "no data" with the reason. Mismatches are listed, never silently rewritten.
- The agent writes, you decide. The agent opens and closes moves and drafts their text. The page marks what the agent wrote and you have not read yet. The outcome of a move, the confirmed cause and the review marks stay yours.
- Everything in one HTML page. The record (
kifu.json) is drawn as a tree you read and edit in the browser. It also includes Duetsheet, an interactive report you review with comments and free-hand regions drawn on charts.
About the name: a kifu is the record of a shogi or go game, move by move. Players replay it afterwards to see where the game turned and which moves were mistakes. In a duet, two play from the same sheet: a researcher and an AI agent.
Demo GIFs
1. Reading the research record as a tree
What the GIF shows: the research record of the demo project drawn as a tree. Clicking a move opens its reason, result and data chain. The shape of a move tells how it ended (holds, dead end, correction, independent audit, not resolved, planned).
2. Ask the AI agent while you read
What the GIF shows: draw around part of a figure, pick a question such as "Where does the data come from?", "How was it computed?" or "Can it be trusted?", and send it. The agent answers in a floating panel.
3. Arrange the page
What the GIF shows: blocks (question, tree, move, main path) are dragged, folded to one row, resized or shown full screen.
4. Edit a move, then undo and redo
What the GIF shows: changing the cause of a dead end, then taking the change back with Undo and bringing it back with Redo. Every edit is recorded with who made it and when.
Quick start
You need Python 3.8 or later. It uses only the standard library, so there is nothing else to install.
With Claude Code (terminal, VS Code or JetBrains), install once:
/plugin marketplace add Ashur5457/duetkifu /plugin install duetkifu@duetkifu
Then ask Claude to start Duetkifu on your data folder (the /duetkifu skill).
Without a plugin, run it directly:
python duetkifu.py "path/to/your/data/folder"
The page opens in your browser, connected to the folder. Raw data is only read; the record and report are stored in a duetkifu/ subfolder. The interface is available in English, Traditional Chinese, Simplified Chinese, Japanese, Korean and Spanish.
FAQ
What is Duetkifu? An open-source research record and report reviewer for researchers working with AI agents. It keeps every move, dead ends included, with where each number comes from.
Which AI agents does it work with? Claude Code, Codex, Gemini CLI, Cursor, or any agent that can edit JSON files (see AGENTS.md).
Is it free? Yes, MIT license. It is a v0.8 prototype, so feedback is welcome.
How is it different from a lab notebook or chat history? Moves are structured (parent, reason, result, cause of failure), numbers are checked against recomputation and file fingerprints, and the whole path is drawn as an editable tree.
If you try it and something breaks or is missing, open an issue on GitHub or leave a comment here.
Keywords: research record, research log, lab notebook for AI agents, dead ends, negative results, reproducibility, provenance, data lineage, human-AI collaboration, Claude Code plugin, Codex, Gemini CLI, kifu, Duetkifu, Duetsheet.
