Coding agents
Coding agents such as Claude Code and Codex can read and edit your data on your computer.
They use three doors: the files in your folder, a read-only copy of the database, and the
kzx tool (or MCP). Every edit is checked, logged and undoable.
Set it up today
kzx is one program with two jobs. In a terminal it is a command-line tool. With kzx mcp it
is an MCP server: MCP (Model Context Protocol) is the standard way an AI app such as Claude
Code or Codex talks to a tool. The server is named kaizendex-v2, so it sits beside the
old app’s kaizendex server.
-
Build
kzxonce, in the repository folder:cargo build --release -p kzx. The program is thentarget\release\kzx.exein the repository.kzxis not on yourPATH(the list of folders your terminal looks in) until you move to the new app, so use the full path. -
Check it:
kzx doctorprints the data folder, the folder sync, and the exactclaude mcp addline with the real path. -
Add it to Claude Code, read only:
Terminal window claude mcp add --scope user kaizendex-v2 -- "C:\path\to\kzx.exe" mcpTo let Claude Code write too:
Terminal window claude mcp add --scope user kaizendex-v2 -- "C:\path\to\kzx.exe" mcp --allow-writes -
Or add it to Codex, in
~/.codex/config.toml:[mcp_servers.kaizendex-v2]command = 'C:\path\to\kzx.exe'args = ["mcp"]For writes, use
args = ["mcp", "--allow-writes"].
Replace C:\path\to\kzx.exe with the real path, for example
C:\Users\<you>\…\kaizendex-v2\target\release\kzx.exe.
- Read only by default.
kzx mcpoffers the 21 read tools. A write tool is refused with “disabled in read-only mode”.--allow-writesoffers all 44 tools. - History names the program. Every change through MCP shows the client’s name, for example “Claude Code”. Undo works on it as on a tap.
- Same tools and rules as the AI in the app. The AI in the app,
kzxand MCP run one set of tools, with the same privacy rules and AI permissions. “No AI” and Hidden collections are refused, and only you change the AI choice, Hidden and a collection’s AI instructions. kzxworks with the desktop app open or closed. When the app owns the folder,kzx sync --waitasks the app to sync and waits. When the app is closed,kzxsyncs the folder itself for one pass.- Every command takes
--json, for scripts. An error prints the message and how to fix it.
Bulk edits: kzx import <file or folder> (add --dry-run to see what would change first), or a CSV
or markdown files dropped into _inbox/. See Bulk edits.
Which door for which job
| Job | Best door | Example |
|---|---|---|
| Read or change one entry, a skill or a setting | the file | edit distance: 5.2 in Collections/Workouts/Morning run.md |
| Create a few entries | new files, or kzx entry add |
a new file in Collections/Tasks/ |
| Bulk edits | a CSV or markdown files dropped into _inbox/, or kzx import |
200 old runs from a spreadsheet, as one undoable step |
| “Find everything about X” | kzx search (words today; meaning later) |
“knee pain” |
| An entry and everything linked to it | kzx context |
a project with its tasks and notes, in one call |
| Precise questions over many rows | SQL on the read-only copy | “open tasks per project, overdue first” |
| An agent with no shell | MCP | Claude desktop |
The full lists are on kzx commands and
MCP tools.
The map in your folder
Your folder starts with an AGENTS.md file, and a CLAUDE.md beside it that imports it
(@AGENTS.md), because Claude Code reads that name. It
tells an agent what each file is, which door to use for which job, and how to edit safely.
Each collection folder also has a _schema.md: its properties, their types and the
allowed tags, in plain words. So an agent knows what to write without opening the database.
When an agent edits a file
- The app reads the change back within a second, through the same rules as a tap.
- If you edit the same entry in the app at the same time, both edits are kept: field by field, and word by word in text.
- An edit that breaks a rule (a word where a number belongs) is not applied. It stays in
the file and is listed in
.kaizendex/problems.md.kzx statusshows it too. kzx sync --waitwaits until every file change is in, so the agent can read its own edit.- Every change shows in history with its source, for example “Claude Code, via the folder”.
See When you or an AI edit the folder.
What a coding agent cannot read
Coding agents run as you, so they can open any file you can. Your folder protects private collections by locking them:
- A collection set to anything but Any AI, or Hidden, has locked files. An agent sees only scrambled bytes. Today, before locked files exist, such a collection is left out of the folder completely.
- Locked collections are left out of the read-only database copy.
kzxand MCP treat every caller as an AI, even you in a terminal. “No AI” refuses. “Ask me first” shows an Approve card in the app that names the program: “An MCP client calling itself “claude-code” wants to read Diary” (the client picks its own name). The call waits up to 2 minutes for your answer. Allow lets it read, and the same program may read that collection again for 10 minutes. No refuses at once. When nobody answers, the call stops with “Approve it in the app, then run the call again”, and the card stays in the app.
What a coding agent cannot change
A coding agent cannot make a change only you can make, such as where a collection lives or its AI setting. It can only suggest one.
Example: Claude Code edits Collections/Diary/_collection.json to set the Diary to Any AI. The
app shows “This change needs your OK in the app” and keeps the old setting. Nothing changes until
you approve it in the app, on your device.
Automations
A coding agent can make and switch on automations for you, if you allow it. Tick “AI can make and switch on automations” in Settings → Security → AI permissions. It is off by default.
| Door | What it does | Needs the checkbox |
|---|---|---|
list_automations (MCP), kzx automations list |
lists your automations, on or off | no |
set_automation (MCP) |
makes or changes one automation | yes |
set_automation_enabled (MCP), kzx automations on / off |
switches one on or off | yes |
delete_automation (MCP) |
deletes one; Undo brings it back | yes |
Example: you ask Claude Code, “When Done is checked on a task, set Stage to Done.”
With the checkbox ticked, it calls set_automation, switched on. The next task you tick moves to
Done. History shows the change as “Claude Code”, and one Undo takes it back.
With the checkbox off, the call is refused. The answer names the permission and links to it:
“The person can allow it in the app: Settings → Security → AI permissions → “AI can make and
switch on automations” (open it: kaizendex://settings/security/ai-automations). Until then,
suggest it: …“. kzx also prints Open the permission: kaizendex://settings/security/ai-automations.
MCP clients get the same link as data (permission.link). The agent tells you what it wants to
do and gives you the link. Open it: the desktop app shows Settings → Security with the
checkbox highlighted. Tick it, or make the automation yourself in More → Automations.
- An automation an agent made runs with the AI’s limits: it never reads or changes a collection closed to AI, and never runs an agent. When you switch it on yourself in the app, it is yours.
Settings/Automations/in your folder stays read-only. Usekzxor MCP, not a file edit.- An agent can never tick the checkbox itself.
Moving a collection to the Trash
A coding agent can move a whole collection to the Trash, if you allow it. Tick “AI can move collections to the Trash” in Settings → Security → AI permissions. It is off by default.
| Door | What it does | Needs the checkbox |
|---|---|---|
delete_collection (MCP), kzx tool delete_collection --args '{"collection":"Old reading list"}' |
moves the collection and its entries to the Trash, as one change | yes |
restore_item (MCP), kind collection |
brings it back from the Trash, with its entries | no |
Example: you ask Claude Code to remove your empty collections. With the checkbox ticked, it calls
delete_collection for each. History shows each change as “Claude Code”, and Undo takes it back.
- With the checkbox off, the call is refused. The answer names the permission and links to it:
kaizendex://settings/security/ai-collections. - An agent never moves a collection closed to AI (No AI, Hidden), or one that holds entries it cannot read.
- Delete for good is always yours, in the app.
Which apps can connect
| App | Coding agents |
|---|---|
| Desktop app | yes: the folder, the database copy, kzx and MCP |
kzx alone (a server, or a computer without the desktop app) |
yes: kzx runs its own engine |
| Web app | linked to the desktop app: yes, through the desktop app’s folder; on its own: no folder |
| Phones | no |
Does it work in my setup?
Example: Claude Code on your laptop asks kzx search "knee pain". This table says when that works.
| Your setup or your data | kzx and MCP on your computer |
A cloud MCP address (later) |
|---|---|---|
| Free, Cloud Sync on | yes | no: it needs Pro |
| Pro, Cloud Sync on | yes | yes |
| Cloud Sync off (desktop app only) | yes | no: it needs Cloud Sync |
| A Cloud Sync collection | yes | yes, on Pro |
| A Cloud Sync, end-to-end encrypted collection | yes | only with a key you give that connection |
| A This device only collection | yes, on the device that holds it | never |
| A No AI collection | refused | refused |
| Hidden entries | refused | refused |
- On your computer,
kzxworks the same in every setup: Cloud Sync on or off, end-to-end encryption on or off. Your own computer can already read your own data. End-to-end encrypted means only your devices hold the key, and your computer is one of them. - Your privacy choices still apply. “No AI” collections are never given to AI tools. “Ask me first” waits for your Approve. Locked files stay locked. Hidden stays hidden.
- A cloud MCP address (later) lets cloud AI tools, such as Claude Code on the web, reach your data while your computer is off. It reads your data in Cloud Sync, so it needs Pro.
Version the folder with Git
The desktop app can version this folder with Git. It saves the text files to Git on a schedule, and can push them to a private GitHub repository. The database copy is never saved to Git. Collections set to This device only are never pushed.