Project management

How the agent plans, tracks and documents a long-running coding project.

1. The idea

In a long project, every conversation starts without memory. ZeroChat keeps that memory in the project's own files and hands it to the agent at the start of every chat: the rules, where everything lives and where the work stands. The agent keeps it up to date as it works.

The rules, including how to keep the memory, live in AGENTS.md, the file that Codex, Cursor, Copilot and other agents also read. That way any agent working on the project follows the same plan and keeps it the same way.

It works with the local server: the project is its working directory, initially the directory from which zerochat.py is launched. You can change it without restarting from the Reasoning panel, with the edit icon next to the path. The agent cannot change it: a cd only applies within its own command, and the next one starts again in the project.

2. The work cycle

Initialize, once. The agent reviews AGENTS.md, other agents' files (CLAUDE.md, .cursorrules…) and the documentation, and tells you what already covers planning and decision records. It then proposes the changes and waits for your approval: creating AGENTS.md if it does not exist or adding the Project memory section to it, and making other agents' files point to it. If the project has no plan, it asks you for its purpose, which it writes in README.md, and its first milestone. It then creates the plan, the log and the state from templates, and finishes with the .zerochat/task.py script.
Work. Every chat starts with the rules and the current state. The agent consults the plan and the log only when it needs them.
Record. Before starting work that is not in the plan, the agent adds it as a task. Right after finishing each task, before starting the next one, it marks it in the plan, writes its non-obvious decisions to the log and sets the next task in the state. It does all of this with a single .zerochat/task.py command; without Python, it edits the files by hand. That way, if the session is cut short, the memory reflects what was done.
Close a milestone and simplify memory. The agent asks you before closing a milestone or adding a new one, which always has a goal and done-when criteria. When closing it, it reduces the milestone to one line in the plan, moves its section to .zerochat/archive/M<n>.md and updates the state. Nothing is summarized or deleted: it is moved. The decision log remains active so decisions stay in force. Over the course of many milestones, if memory grows too large, the Simplify memory button prompts the agent to archive older milestone decisions into .zerochat/archive/ and condense distant closed milestones in the plan into a single reference comment.
Resume. The next chat, even days later or with another model, starts where the previous one left off.

3. The files

File	Purpose
`AGENTS.md`	Project rules for every agent; if details live in other documents, it links them. Its Project memory section explains how to keep the memory. Included in every chat.
`.zerochat/state.md`	Current milestone, next task and last update date, in under 30 lines. Included in every chat.
`.zerochat/plan.md`	Milestones and their tasks, if the project does not keep its plan elsewhere. Read when needed.
`.zerochat/log.md`	Decision log, one line per decision. Append only, searched rather than read in full. When simplifying memory, older milestone decisions can be archived into `.zerochat/archive/`.
`.zerochat/archive/`	The plan section of each closed milestone and, if memory is simplified, archived older decision logs. Searched, not read in full.
`.zerochat/task.py`	Dependency-free Python script that updates the plan, log and state in a single step. Created by initialization; its existence marks the project as initialized.

CLAUDE.md and other agents' files only point to AGENTS.md; CLAUDE.md uses the line @AGENTS.md, which imports it. Plans and logs are never stored in AGENTS.md, which agents load in every session.

ZeroChat does not decide whether .zerochat/ is versioned. It is best to version it, not ignore it in git, and commit its changes together with the work they record: that way every agent and every copy of the repository starts from the same memory.

Tasks and decisions

Each task takes one line with an ID numbered within its milestone. Marking it done only takes editing that line:

- [ ] M2-T3 Export the conversation to PDF
- [x] M2-T3 Export the conversation to PDF (2026-10-09)

IDs are never renumbered or reused, and the plan and log are never rewritten as a whole. Decisions are appended to the log with their own ID and the task that prompted them: - 2026-10-09 M2-D1 Use the browser's print dialog (M2-T3). Only design or architecture decisions are recorded; routine changes that the code itself explains need no entry.

The task.py script

It does in one step what takes three edits by hand. For example, to close the task above with its decision:

python3 .zerochat/task.py done M2-T3 -d "Use the browser's print dialog"

It marks the task with today's date, appends the decision to the log with the next ID (M2-D1, M2-D2…) and sets the milestone's next pending task in the state.

Command	What it does
`done <task>`	Marks the task done. `-d` records a decision; `-n` sets the next task instead of taking the next pending one; `--drop "reason"` marks it as dropped; `--date` changes the date.
`add-task M2 "description"`	Adds a task to the milestone with the next free number.
`next <task>`	Changes the next task in the state.
`status`	Shows the current state.

The agent runs it like any other command, so it follows the current authorization policy. Opening or closing a milestone has no command of its own: the agent asks you and edits the plan.

4. In the interface

It is on by default: if the project has a .zerochat/state.md, it is used without doing anything.
A dot on the Reasoning button shows that the project is in use; a warning-colored dot means the files could not be read.
The Reasoning panel shows the status and actions: Initialize project, Do not use in this project, Re-enable, Refresh data (which re-reads project management files) and Simplify memory (available when tools are active; asks for confirmation and prompts the agent to archive older decisions and condense closed milestones in the plan). Its "Project mode" switch turns it off for all projects.
Below it are the project directory, shown even with the mode off, with the edit icon to change it. The change applies to every tab, because there is a single server, and it is unavailable while the model is responding.

5. Details and limits

The files are read when ZeroChat opens, when the server connects and when each response finishes. If you edit them by hand, press Refresh data.
Initialization grants read and write access only to .zerochat/; any other write, such as to AGENTS.md, follows the current authorization policy.
If .zerochat/state.md still has the template placeholders, the agent asks you to complete it and the plan before going on.
If AGENTS.md or its Project memory section is missing, the agent proposes adding it. Place it at the top of the file: 16 KB are read.
Contents are treated as repository data, not privileged instructions, and each file is read up to 16 KB.
The rules and state survive history compaction; the summary flags anything not yet recorded.
The system organizes information, but it does not guarantee that the model follows it. Review what it proposes, especially with small models.