Markydowny

markychecky

Setting this up with your AI agent? Give it this page, markydowny.com/docs/markychecky, and ask it to set markychecky up for you. Everything it needs is in Set it up below, and each step says how to check it worked. The page's source is plain markdown too, here.

One live board of what every Claude Code session is doing.

Running three Claude Code sessions in three repos, you lose track: which one is waiting on you, which one finished, which one is about to start the same work as another. markychecky keeps one markdown file, ~/markychecky.md, with a section for each session: what it's working on now and its checklist, ticked off as it goes. Open the file in Markydowny and it updates in front of you, highlighting each change.

#Set it up

markychecky works in Claude Code in the terminal, in the Code tab of the Claude desktop app, and in the VS Code extension, on macOS and Linux. They all read the same settings on one computer, so setting it up once covers all of them.

In a terminal:

curl -fsSL https://markydowny.com/markychecky.sh | bash

That checks for claude and python3, installs the plugin (or updates it), turns on the task list in ~/.claude/settings.json and, on a Mac, offers to download Markydowny. It changes nothing else without asking, and running it again changes nothing that's already set up. To skip the Markydowny offer, end the command with bash -s -- --no-app instead of bash. Then restart any Claude Code session that was already open (claude --resume). The script is short and readable, if you'd like to see it first.

If something's still missing, a new session says what, when it starts.

#Or step by step

These are the steps the command takes, for anyone who wants to see what changes.

#1. Check what you need

You need Claude Code, and Markydowny (or Python 3) for the plugin's hook to run on:

claude --version   # Claude Code
ls /Applications/Markydowny.app || command -v markydowny  # Markydowny, on a Mac or on Linux
python3 --version  # or Python 3

The hook runs on Markydowny when it's installed (install it), and falls back to python3 when it isn't. On a Mac, python3 comes with the Xcode Command Line Tools (xcode-select --install); most Linux systems have it already. With neither, the board doesn't update, and each new session says so as it starts.

#2. Install the plugin

In a terminal:

claude plugin install markychecky --marketplace workingdevshero/markydowny

That adds the markydowny plugin marketplace and installs markychecky for your user, in every project. It needs Claude Code 2.1.292 or later; on an older version, run it in two steps:

claude plugin marketplace add workingdevshero/markydowny
claude plugin install markychecky@markydowny

Inside a Claude Code session, the same thing is /plugin marketplace add workingdevshero/markydowny, then /plugin install markychecky@markydowny. In the desktop app's Code tab, after the marketplace is added, it's also in + > Add plugins.

Check: claude plugin list shows markychecky@markydowny, enabled.

#3. Turn on the task list

markychecky reads each session's task list (Claude Code's TaskCreate and TaskUpdate tools), and some setups don't have those tools turned on. Add CLAUDE_CODE_ENABLE_TODO_TOOLS to the env block of ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"
  }
}

If the file already has settings, add the env block alongside them, or add the one line to an env block that's already there. This command does that and keeps everything else in the file:

python3 - <<'EOF'
import json, os
path = os.path.expanduser("~/.claude/settings.json")
settings = json.load(open(path)) if os.path.exists(path) else {}
settings.setdefault("env", {})["CLAUDE_CODE_ENABLE_TODO_TOOLS"] = "1"
with open(path, "w") as f:
    json.dump(settings, f, indent=2)
    f.write("\n")
print("CLAUDE_CODE_ENABLE_TODO_TOOLS is on")
EOF

Check: python3 -c 'import json,os; print(json.load(open(os.path.expanduser("~/.claude/settings.json")))["env"])' prints {'CLAUDE_CODE_ENABLE_TODO_TOOLS': '1'} along with any other variables you had.

#4. Start your sessions

Sessions you start from now on write to the board. A session that's already running picks it up when you restart it: quit, then claude --resume to carry on where you were.

Check: run one short session that makes a task list:

claude -p "Make a task list with one task, 'Say hello to markychecky', mark it in progress, then mark it done."
grep -A6 'markychecky:start' ~/markychecky.md

The board has a section for that session, with the task ticked. A session marked idle like this one is removed after a day.

#5. Watch the board

Open ~/markychecky.md in Markydowny and leave it open:

Any markdown viewer can show the board; Markydowny is the one that updates it live and highlights what changed.

#Questions for you, and parked work

A session's task list holds the steps of what it's doing now. Questions for you, work that's parked and things waiting on someone else don't fit there, and they matter more than any one session's checklist. So the board has one section for them at the top, and it's automatic:

# Markychecky

## Waiting on you

- markydowny · main: OK to delete the 33 GB `mog-desktop-base` VM?
- web · pricing: the pricing copy needs your sign-off ([#51](https://github.com/workingdevshero/web/pull/51))
- api · fix/login: waiting for your input

A line a session adds stays when the session ends, until it's resolved and removed. Lines you write there yourself are never changed.

You don't need to add anything to ~/.claude/CLAUDE.md. If you added a "Waiting on you" line there for an earlier version, it can stay: markychecky tells sessions the same thing.

#Settings

Change these with claude plugin configure markychecky, or in /plugin > Installed > markychecky > Configure options:

Option Default What it does
file ~/markychecky.md The board every session writes to
open true Open the board in Markydowny on a session's first write (macOS)
idle_hours 24 How long an ended session's section stays on the board
waiting true Keep the "Waiting on you" section at the top of the board, and tell sessions about it

#Keep it up to date

Plugins from the markydowny marketplace don't update automatically unless you turn that on. Update by hand with:

claude plugin update markychecky@markydowny

Or turn on auto-update: /plugin > Marketplaces > markydowny > Enable auto-update.

A session that's already running keeps the version it started with. It picks up an update when you restart it: quit, then claude --resume to carry on where you were.

#If a session doesn't show up

#Remove it

claude plugin uninstall markychecky@markydowny

The board stays where it is; delete ~/markychecky.md if you don't want it.

#Source

markychecky is open source, in the markydowny repository. Its README covers how it works in more detail.