Skip to content

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.

Claude Code uses three doors: the files, the read-only database copy, and kzx or MCP. File edits and kzx writes go through the app’s checks into the live database. The copy is for reading only.Claude Codeor CodexFilesCollections/Workouts/*.mdkaizendex.sqliteread only, for SQLkzx or MCPsearch, context, importThe appchecks, logs,undo
Read with SQL, write with files or kzx. The database copy is refreshed from the app, never the other way.

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.

  1. Build kzx once, in the repository folder: cargo build --release -p kzx. The program is then target\release\kzx.exe in the repository. kzx is not on your PATH (the list of folders your terminal looks in) until you move to the new app, so use the full path.

  2. Check it: kzx doctor prints the data folder, the folder sync, and the exact claude mcp add line with the real path.

  3. Add it to Claude Code, read only:

    Terminal window
    claude mcp add --scope user kaizendex-v2 -- "C:\path\to\kzx.exe" mcp

    To let Claude Code write too:

    Terminal window
    claude mcp add --scope user kaizendex-v2 -- "C:\path\to\kzx.exe" mcp --allow-writes
  4. 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 mcp offers the 21 read tools. A write tool is refused with “disabled in read-only mode”. --allow-writes offers 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, kzx and 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.
  • kzx works with the desktop app open or closed. When the app owns the folder, kzx sync --wait asks the app to sync and waits. When the app is closed, kzx syncs 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 status shows it too.
  • kzx sync --wait waits 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.
  • kzx and 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. Use kzx or 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, kzx works 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.