Self-hosted, sharable kanban for humans and agents. One 4.7 MB binary, 5 MB of RAM, 10 to 60 tokens per agent reply, starts in 3 ms, zero setup.
Rust ai-agentsclaude-codeclicodexcoding-agentskanbanlocal-firstmcpmcp-servermodel-context-protocolproductivityproject-managementraspberry-pirustself-hostedsqlitetask-manager
Move the development notes into CONTRIBUTING
emanuele-em54728c0da279
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdnew file mode 100644index 0000000..e758439--- /dev/null+++ b/.github/CONTRIBUTING.md@@ -0,0 +1,65 @@+# Contributing to Kanzo++Thanks for helping. Kanzo is small on purpose: every change is weighed by how light and fast it keeps the board, and how few tokens it costs agents.++- **A bug or an idea:** open an issue first for anything bigger than a small fix, so we can agree on the approach.+- **A security problem:** don't open an issue; see [SECURITY](SECURITY.md).++## Build and test++```sh+cargo test # store, config, export, web and service tests+cargo run # the board, with data in ~/kanzo+cargo run -- --home /tmp/k --port 4300 # a throwaway board+```++Before sending a change, run what CI runs, on the latest stable Rust:++```sh+cargo fmt --check+cargo clippy --all-targets --locked -- -D warnings+cargo test --locked+```++For a change to the board, also try it in a browser, in light and dark mode.++## What a good change looks like++- **Light.** No new dependency without a strong reason. If it could cost speed or memory, measure before and after.+- **Few tokens.** MCP replies stay short plain text; say what a change does to their size.+- **Plain web.** The board is HTML, CSS and JavaScript with no build step, and runs on Safari 13.1, Chrome 80 and Firefox 78.+- **Small commits.** One change per commit, with a short imperative subject and a body that says why.++## The code++Where things are:++| File | Does |+| --- | --- |+| `src/main.rs` | Command line |+| `src/home.rs` | Data folder and `config.toml` |+| `src/schema.sql` | The database schema |+| `src/store.rs` | All SQL |+| `src/mcp.rs` | The MCP tools, over stdio and HTTP (`rmcp`, pinned on purpose: it still changes often) |+| `src/web.rs` | The board's HTTP API, and `/mcp` |+| `src/index.html`, `src/app.js`, `src/logo.png` | The board UI: plain HTML, CSS and JavaScript, built into the binary |+| `src/sync.rs` | `kanzo sync` |+| `src/export.rs` | `kanzo export` |+| `src/service.rs` | `kanzo service` |++## How it stays light++- **One thread** runs the server; database work goes to at most 8 helper threads, which exit when idle.+- **One short SQLite connection per operation,** with a 5-second busy timeout, so the board and any number of agents can write at once, and `kanzo sync` can safely swap the file between operations. The database uses a rollback journal instead of WAL, because with short connections WAL created and deleted two files on every request. Now a read touches no extra files, and each operation is about 3 times faster.+- **Cheap polling:** the board asks for a change token every 2 seconds, only while its tab is visible, and waits for each answer before asking again. Database triggers bump the token on every write.+- **Small pages:** the board loads only the newest 50 done tasks until you ask for more or search, so a board that has piled up thousands of done tasks reloads as fast as a new one.+- **Few tokens for agents:** MCP replies are short plain text, and the tool list agents read at the start of every session is kept small (about 3 KB).+- **Release profile:** `opt-level = "s"` with full LTO measured 30% smaller than the default at the same speed.++Measured on a 64-bit ARM Linux container limited to 64 MB of memory and half a CPU: 3.5 MB of memory and one thread when idle, 4.3 MB after 200 tasks.++## Releases and dependencies++Releases are built by [cargo-dist](https://github.com/axodotdev/cargo-dist): push a tag like `v0.1.0` and GitHub Actions builds every target and the installer, on Ubuntu 26.04 LTS and macOS 26. `.github/workflows/release.yml` is generated: change `dist-workspace.toml` and run `dist generate`, never edit the file by hand.++Dependabot opens a weekly pull request when a crate or a GitHub Action has a new version.diff --git a/docs/guide.md b/docs/guide.mdindex 4d81912..7fad9bf 100644--- a/docs/guide.md+++ b/docs/guide.md@@ -135,36 +135,4 @@ kanzo sync --keep-remote # take GitHub's board; this laptop's is kept in kanzo## Development-```sh-cargo test # store, config, export, web and service tests-cargo run # the board, with data in ~/kanzo-cargo run -- --home /tmp/k --port 4300 # a throwaway board-```--The code is small on purpose:--| File | Does |-| --- | --- |-| `src/main.rs` | Command line |-| `src/home.rs` | Data folder and `config.toml` |-| `src/schema.sql` | The database schema |-| `src/store.rs` | All SQL |-| `src/mcp.rs` | The MCP tools, over stdio and HTTP (`rmcp`, pinned on purpose: it still changes often) |-| `src/web.rs` | The board's HTTP API, and `/mcp` |-| `src/index.html`, `src/app.js`, `src/logo.png` | The board UI: plain HTML, CSS and JavaScript, built into the binary |-| `src/sync.rs` | `kanzo sync` |-| `src/export.rs` | `kanzo export` |-| `src/service.rs` | `kanzo service` |--### How it stays light--- **One thread** runs the server; database work goes to at most 8 helper threads, which exit when idle.-- **One short SQLite connection per operation,** with a 5-second busy timeout, so the board and any number of agents can write at once, and `kanzo sync` can safely swap the file between operations. The database uses a rollback journal instead of WAL, because with short connections WAL created and deleted two files on every request. Now a read touches no extra files, and each operation is about 3 times faster.-- **Cheap polling:** the board asks for a change token every 2 seconds, only while its tab is visible, and waits for each answer before asking again. Database triggers bump the token on every write.-- **Small pages:** the board loads only the newest 50 done tasks until you ask for more or search, so a board that has piled up thousands of done tasks reloads as fast as a new one.-- **Few tokens for agents:** MCP replies are short plain text, and the tool list agents read at the start of every session is kept small (about 3 KB).-- **Release profile:** `opt-level = "s"` with full LTO measured 30% smaller than the default at the same speed.--Measured on a 64-bit ARM Linux container limited to 64 MB of memory and half a CPU: 3.5 MB of memory and one thread when idle, 4.3 MB after 200 tasks.--Releases are built by [cargo-dist](https://github.com/axodotdev/cargo-dist): push a tag like `v0.1.0` and GitHub Actions builds every target above and the installer. CI runs `cargo fmt`, `clippy` and the tests on Linux and macOS for every push.+See [CONTRIBUTING](../.github/CONTRIBUTING.md): how to build, test and send a change, a map of the code, and how Kanzo stays light.