{"slug": "kechup-a-simple-cli-task-tracker-for-ai-agents", "title": "Kechup – a simple CLI task tracker for AI agents", "summary": "A developer released kechup, a command-line task tracker that stores AI agent tasks, claims, notes and history in the project folder and in git so a new agent session can read what the last one did. kechup requires Python 3.12 or newer and git, uses only the Python standard library, needs no server, database, account, network access or API key, and is installed via `pip install kechup`; it does not support Windows because it relies on `fcntl` file locks. Every kechup write is one git commit authored with the agent ID, a task closes only when its REPORT.md is committed and clean, and a plain `git revert` of finished work reopens the task and re-blocks the tasks that depend on it.", "body_md": "kechup is a command-line task tracker for one project folder, made for AI agents and the people who run them.\n\nThe problem: a new agent session does not know what the last session did. kechup keeps the tasks, claims, notes and history in the project folder and in git, so the next session can read them.\n\n```\n# In a project folder made with `kechup new`:\nkechup add task \"Write the FAQ\" --by alice\nkechup next --claim --by agent-1\necho \"The FAQ is done.\" > tasks/T1-write-the-faq/REPORT.md\nkechup commit tasks/T1-write-the-faq/REPORT.md -m \"FAQ report\" --task T1 --by agent-1\nkechup done T1 --evidence tasks/T1-write-the-faq/REPORT.md --by agent-1\n```\n\n`keche.md` is the project notes file. After `kechup new`, kechup changes only its Work section, and every kechup write keeps that section current.\n\nkechup uses the Python standard library and the `git` command. It has no other dependencies.\n\nAgents forget. kechup puts the project state in the project folder, where every agent can read it:\n\n- `keche.md` has a**Work** section that shows what is doing, blocked, todo, and done.\n- `.kechup/tasks.json` holds the tasks.\n- git holds the history. Every kechup write is one git commit, with the agent ID as the author.\n\n`keche.md` is a plain Markdown file with notes about the project: the goal, the decisions, and the open questions. An agent reads it first when it starts work. kechup changes only the Work section. You write the rest.\n\nkechup also watches git. If someone reverts accepted work with a plain `git revert`, kechup shows the task as reverted, and the tasks that depend on it become blocked again.\n\n- **Only Python and git.** kechup needs no server, no database, no account, no network access and no API key. It runs on a locked-down server and in a sandbox.\n- **git is the only record.** kechup keeps no second copy of the state. Every claim, note and close is one git commit, with the agent ID as the author. Use`git log` ,`git blame` and`git revert` to review agent work.\n- **Done needs evidence.** A task closes only when its`REPORT.md` is committed and clean. A status change alone does not close a task.\n- **kechup follows git.** A plain`git revert` of finished work reopens the task. The tasks that wait for it become blocked again.\n- **Safe for many agents.** A lock stops two agents from claiming the same task.`kechup next` gives the next task with no open blockers.\n- **Small footprint.** Setup adds`.kechup/` , the Work section of`keche.md` , a`.gitignore` if the project has none, and one git hook.\n- **Made for agents.** Every command accepts`--json` and returns stable error codes.`kechup help` prints the full agent guide.\n\nkechup is a good choice when you want agent work to stay in plain git, with a clear trail and a clear close. Use a different tool if you need a visual board, sync between machines, or tasks that an AI writes for you.\n\n- Python 3.12 or newer\n- git\n- Linux or macOS\n\nWindows is not supported. kechup uses `fcntl` file locks, and Windows does not have `fcntl`.\n\n```\npip install kechup\nkechup --help\n```\n\nOr install it as an isolated command with [pipx](https://pipx.pypa.io/):\n\n```\npipx install kechup\nkechup --help\n```\n\nFor development, install from a clone:\n\n```\ngit clone https://github.com/erogol/kechup\ncd kechup\npip install -e .\n```\n\nkechup does nothing until your agent knows about it. Use one of these two methods.\n\n**Instruction file.** Add these lines to the instruction file of your agent, for example `AGENTS.md` or `CLAUDE.md`:\n\n```\n## Tasks\n\nThis project uses kechup for tasks. Run `kechup help` once before you start work.\nPass `--by <your agent id>` on every kechup write command. Use one ID for the whole session.\nFind work with `kechup next --claim`. Write the result to the REPORT.md in the task folder.\nCommit with `kechup commit`, not with a plain `git commit`.\nClose the task with `kechup done` after its tests and review pass.\n```\n\n**Skill file.** If your agent supports skills, copy `skills/kechup/SKILL.md` from this repo into its skill folder.\n\nTo check the setup, ask the agent to \"take the next kechup task\". The agent must run `kechup next --claim` with its ID.\n\n```\n# Start a new project. alice is the project owner.\nkechup new my-project --goal \"Ship the beta FAQ\" --owner alice --by alice\ncd my-project\n\n# Or bring an existing folder under kechup (dry run first).\n# The folder must have a keche.md file.\nkechup adopt ../old-project --dry-run --owner alice --by alice\nkechup adopt ../old-project --owner alice --by alice\n\n# Add tasks. T2 waits for T1.\nkechup add task \"Write the FAQ\" --by alice\nkechup add task \"Send the invites\" --after T1 --by alice\n\n# An agent takes the next task and works on it\nkechup next --claim --by agent-1\nkechup note T1 \"Draft is in tasks/T1-write-the-faq/\" --by agent-1\necho \"The FAQ is done.\" > tasks/T1-write-the-faq/REPORT.md\nkechup commit tasks/T1-write-the-faq/REPORT.md -m \"FAQ report\" --task T1 --by agent-1\n\n# The agent closes the task after its tests and review pass\nkechup done T1 --evidence tasks/T1-write-the-faq/REPORT.md --by agent-1\n\nkechup list\n```\n\nEvery write command needs an agent ID. Give it in one of two ways:\n\n```\nkechup claim T1 --by agent-1\n# or\nexport KECHUP_AGENT=agent-1\nkechup claim T1\n```\n\n`--by` wins when both are set. A blank ID is refused. A write command without an ID stops with exit code 3.\n\nThe agent ID becomes the git author of the commit. Use a stable ID, for example `agent-1` or `claude:session:42`. If your agent's prompt gives it an agent ID, use that ID.\n\nEach project has one owner. Only the owner can run `config set-owner`. Any agent can run `done`.\n\nSet the owner with `--owner <id>` on `new` or `adopt`. Without `--owner`, the owner ID is `owner`. Change the owner later with `kechup config set-owner <id>`.\n\n```\nmy-project/\n├── keche.md              # project notes; kechup owns the Work section\n├── .gitignore\n├── .kechup/\n│   ├── tasks.json        # tasks\n│   └── config.json       # project owner and settings\n└── tasks/\n    └── T1-write-the-faq/\n        └── REPORT.md     # the result of the task\n```\n\nkechup writes only between the Work section markers in `keche.md`. Do not edit that section by hand. The rest of `keche.md` is yours.\n\nThe Work section looks like this:\n\n```\n## Work (kechup — do not edit)\n\nDoing:\n- (none)\n\nBlocked:\n- T2: Send the invites (waits for T1 (work reverted))\n\nTodo:\n- (none)\n\nDone (last 5):\n- T1: Write the FAQ (WORK REVERTED by e0add5b (agent-1))\n\n<!-- kechup:end -->\n```\n\nA task stores one of four states: `todo`, `doing`, `done`, `dropped`.\n\nkechup also computes a **displayed** state when you read the tasks. It never stores this state:\n\n| Displayed state | Meaning | \n|---|---|\n| `blocked` | The task has a block reason, or a task in its `after` list is not done. | \n| `doing (stale)` | The claim is older than 24 hours. Any agent can take the task. | \n| `done — <flag>` | The task is done, but kechup found a problem. Example: `done — WORK REVERTED by e0add5b (agent-1)` . | \n\n`kechup list --state open` shows the tasks that are not done and not dropped.\n\n| Command | Purpose | \n|---|---|\n| `kechup new <name> --goal \"<text>\" [--owner <id>]` | Make a new project folder. | \n| `kechup adopt <folder> [--dry-run] [--owner <id>]` | Bring an existing folder with a `keche.md` file under kechup. | \n| `kechup add task \"<title>\" [--after T1,T2] [--priority N] [--folder <path>]` | Add a task. | \n| `kechup list [--state todo\\|doing\\|blocked\\|done\\|dropped\\|open]` | List the tasks. | \n| `kechup next [--claim]` | Show the next open task. `--claim` also claims it. | \n| `kechup claim T<n>` /`kechup unclaim T<n>` | Take or release a task. | \n| `kechup note T<n> \"<text>\"` | Add a progress note to a `doing` task. Any agent can add a note. The note records its author. | \n| `kechup block T<n> --reason \"<text>\"` /`kechup unblock T<n>` | Block or unblock a task by hand. | \n| `kechup assign T<n> --to <id>` | Give a task to an agent. | \n| `kechup done T<n> --evidence <path>` | Close the task. Any agent can do this. The task must have a committed `REPORT.md` . | \n| `kechup reopen T<n> --reason \"<text>\"` | Open a done task again. | \n| `kechup drop T<n> --reason \"<text>\"` | Drop a task. | \n| `kechup dep add T<n> --after T<m>` /`kechup dep rm T<n> T<m>` | Add or remove a dependency. | \n| `kechup show [T<n>] [--rebuild-md]` | Show the project or one task. `--rebuild-md` writes the Work section again and commits it. | \n| `kechup log T<n>` | Show the git history of a task. | \n| `kechup commit <paths> -m \"<text>\" [--task T<n>]` | Commit only the given files. | \n| `kechup approve T<n> <kind>` | Make the git tag `T<n>-<kind>-approved` . | \n| `kechup snapshot` | Commit the changed project files and log reverts. For a scheduled job. | \n| `kechup config set-owner <id>` | Change the project owner. Owner only. | \n| `kechup repair` | Fix the hook and the Work section after a crash. | \n\nAll write commands take `--by <id>`. Use `kechup <command> --help` for details.\n\n`kechup help` prints the full agent guide: the agent loop, the rules, every command, and every error code. Give it to an agent before it starts work. `kechup help --json` returns the same guide in the JSON envelope.\n\nAdd `--json` to any command for machine output:\n\n```\n{\"kechup_json\": 1, \"ok\": true, \"command\": \"list\", \"data\": {\"tasks\": []}}\n```\n\nAn error looks like this:\n\n```\n{\"kechup_json\": 1, \"ok\": false, \"command\": \"claim\", \"error\": {\"code\": \"unknown_task\", \"message\": \"...\"}}\n```\n\n| Code | Meaning | \n|---|---|\n| 0 | Success | \n| 1 | Bad input, for example an unknown task ID | \n| 2 | State conflict, for example a task that another agent claimed | \n| 3 | Environment error: no agent ID, lock timeout, git failure, or a safety refusal | \n\n- kechup commits only the files that it changes or that you name. It never runs `git add -A` . A file that another agent staged stays out of the kechup commit.\n- kechup refuses a file over 5 MB and a file with a secret-like name, for example `id_rsa` ,`.env` or`.env.local` . This check looks only at file names, not at file content.`snapshot` skips these files and lists them in its output.\n- `adopt` checks the folder first. It refuses large files and secret-like files that`.gitignore` does not exclude. The default`.gitignore` excludes media files, model checkpoints, virtual environments,`secrets/` , and`.env` .\n- kechup never writes to a git repository that it did not create or adopt.\n\nTo undo work, use plain git:\n\n```\ngit -c user.name=agent-1 -c user.email=agent-1@kechup.local revert --no-edit <commit>\n```\n\nkechup finds the revert at the next read. The task shows `done — WORK REVERTED by <commit> (<author>)`, and the tasks that wait for it become blocked. The next kechup write command, or `kechup snapshot`, records the revert in the git log and updates the Work section.\n\nIf the task must be done again, run `kechup reopen T<n> --reason \"<text>\"`.\n\nkechup installs a `prepare-commit-msg` hook. The hook marks a revert commit when the commit message does not have the standard git revert line. If the project already has a different `prepare-commit-msg` hook, kechup does not replace it. The command stops with `foreign_hook`. Move the old hook away or merge it by hand, then run the command again.\n\nMany agents can use one project at the same time. kechup takes a lock on `.kechup/lock` for every write. Two agents cannot claim the same task. `new` and `adopt` use a separate lock in the system temp folder, one folder for each user. Set `KECHUP_LOCK_DIR` to move that lock folder.\n\n- It does not judge the quality of work. `done` checks only that`REPORT.md` exists and that you gave evidence.\n- It does not start agents, schedule work, or send messages.\n- It does not sync between machines. One project folder lives on one machine.\n\n```\npython3 -m pytest -q\n```\n\nThe tests use real temporary git repositories and the real `git` command. They do not use mocks for git.\n\nVersion 1.0.0. MIT license. See `LICENSE`.", "url": "https://wpnews.pro/news/kechup-a-simple-cli-task-tracker-for-ai-agents", "canonical_source": "https://github.com/erogol/kechup", "published_at": "2026-10-27 15:31:12+00:00", "updated_at": "2026-10-27 15:41:39.856746+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["kechup", "erogol", "Python", "git", "pipx"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/kechup-a-simple-cli-task-tracker-for-ai-agents", "markdown": "https://wpnews.pro/news/kechup-a-simple-cli-task-tracker-for-ai-agents.md", "text": "https://wpnews.pro/news/kechup-a-simple-cli-task-tracker-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/kechup-a-simple-cli-task-tracker-for-ai-agents.jsonld"}}