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
use std::fs::{self, File, OpenOptions, TryLockError};
use std::io;
use std::net::{IpAddr, Ipv4Addr};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::time::{Duration, Instant};
use anyhow::{Context, Result, bail};
use serde::Deserialize;
use crate::store::{self, ImagesOf, Store};
pub const DEFAULT_PORT: u16 = 4242;
const CONFIG_TEMPLATE: &str = r#"# Kanzo settings.
# Port for the board at http://localhost:<port>.
port = 4242
# Address the board listens on. 127.0.0.1 keeps it on this machine. Use
# "0.0.0.0" to open it from other devices, for example when Kanzo runs on a
# Raspberry Pi with no screen. There are no logins: anyone who can reach the
# port can read and change the board, and use its MCP endpoint.
listen = "127.0.0.1"
# Also serve MCP over HTTP at http://localhost:<port>/mcp, for agents
# that cannot start `kanzo mcp` themselves.
mcp_http = true
# The editor that file:/// links in tasks open in, as a full path. Without it,
# macOS uses your default text editor, and other systems can't open them.
# editor = "/usr/local/bin/cursor"
"#;
const GITIGNORE: &str = "\
# SQLite temporary files; kanzo sync makes sure kanzo.db is complete without them.
kanzo.db-journal
kanzo.db-wal
kanzo.db-shm
# Local to this machine.
kanzo.lock
*.bak
# macOS metadata (AppleDouble files appear on exFAT drives).
._*
.DS_Store
";
const LOCK_WAIT: Duration = Duration::from_secs(if cfg!(test) { 1 } else { 10 });
pub const NO_LOCKS: &str = "This folder doesn't support file locks: don't sync while agents are working.";
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Config {
pub port: u16,
pub listen: IpAddr,
/// Before 0.2 this set the columns. Still read, so older files keep working.
#[serde(rename = "statuses")]
_statuses: Option<toml::Value>,
pub mcp_http: bool,
pub editor: Option<PathBuf>,
}
impl Default for Config {
fn default() -> Self {
Self {
port: DEFAULT_PORT,
listen: IpAddr::V4(Ipv4Addr::LOCALHOST),
_statuses: None,
mcp_http: true,
editor: None,
}
}
}
#[derive(Debug, Clone)]
pub struct Home {
pub dir: PathBuf,
pub config: Config,
}
impl Home {
pub fn resolve(flag: Option<PathBuf>) -> Result<PathBuf> {
if let Some(dir) = flag {
return Ok(dir);
}
if let Some(dir) = std::env::var_os("KANZO_HOME").filter(|v| !v.is_empty()) {
return Ok(PathBuf::from(dir));
}
let home = dirs::home_dir().context("cannot find your home folder; set KANZO_HOME")?;
Ok(home.join("kanzo"))
}
pub fn open(dir: PathBuf) -> Result<Self> {
fs::create_dir_all(&dir).with_context(|| format!("cannot create {}", dir.display()))?;
let dir = dir.canonicalize().unwrap_or(dir);
write_if_missing(&dir.join(".gitignore"), GITIGNORE)?;
let mut home = Self { dir, config: Config::default() };
// During a pull, config.toml can be missing or another machine's, until kanzo sync puts it back.
let lock = home.lock_shared()?;
let path = home.dir.join("config.toml");
// Holding the lock, this can only be left by a sync that died during a pull.
let aside = home.config_aside();
if aside.exists() {
fs::rename(&aside, &path).with_context(|| format!("cannot restore {}", path.display()))?;
}
write_if_missing(&path, CONFIG_TEMPLATE)?;
let text = fs::read_to_string(&path).with_context(|| format!("cannot read {}", path.display()))?;
home.config = toml::from_str(&text).with_context(|| format!("{} is not valid", path.display()))?;
drop(lock);
home.store()?.migrate()?;
Ok(home)
}
pub fn db_path(&self) -> PathBuf {
self.dir.join("kanzo.db")
}
/// Where `kanzo sync` keeps this machine's config.toml during a pull; git ignores `*.bak`.
pub fn config_aside(&self) -> PathBuf {
self.dir.join("config.toml.bak")
}
/// Changes when the database file itself is replaced, as `kanzo sync` does
/// when it pulls, so the board reloads even if the pulled change counter
/// happens to equal the old one.
pub fn db_identity(&self) -> u64 {
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
fs::metadata(self.db_path()).map(|m| m.ino()).unwrap_or(0)
}
// No inode on Windows; a replaced file has a new modified time. Not the creation
// time: NTFS keeps it for a file replaced under the same name.
#[cfg(not(unix))]
{
let modified = fs::metadata(self.db_path()).and_then(|m| m.modified()).ok();
let since_epoch = modified.and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok());
since_epoch.map_or(0, |d| d.as_nanos() as u64)
}
}
/// Callers keep it for one operation only, so a database replaced by `kanzo sync`
/// is picked up on the next one. The shared lock lets sync wait for it to finish.
pub fn store(&self) -> store::Result<Store> {
Store::open(&self.db_path(), self.lock_shared()?)
}
fn lock_shared(&self) -> store::Result<Option<File>> {
let lock = self.lock_file().map_err(|e| store::Error::Invalid(format!("{e:#}")))?;
let deadline = Instant::now() + LOCK_WAIT;
loop {
match lock.try_lock_shared() {
Ok(()) => return Ok(Some(lock)),
Err(TryLockError::WouldBlock) if Instant::now() < deadline => {
std::thread::sleep(Duration::from_millis(25))
}
Err(TryLockError::WouldBlock) => {
return Err(store::Error::Busy("kanzo sync is updating the board; try again in a moment".into()));
}
Err(TryLockError::Error(e)) if unsupported(&e) => {
static WARN: std::sync::Once = std::sync::Once::new();
WARN.call_once(|| eprintln!("kanzo: {NO_LOCKS}"));
return Ok(None);
}
Err(TryLockError::Error(e)) => {
return Err(store::Error::Invalid(format!("cannot lock kanzo.lock: {e}")));
}
}
}
}
pub fn open_file(&self, file: &Path) -> Result<(), String> {
let mut cmd = editor_command(self.config.editor.as_deref(), file)?;
let program = cmd.get_program().to_string_lossy().into_owned();
let mut child = cmd
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.map_err(|e| format!("cannot run {program}: {e}; set `editor` in config.toml to its full path"))?;
// An editor's command can run for as long as the editor does: this isn't work for a database thread.
std::thread::spawn(move || child.wait());
Ok(())
}
pub fn images(&self) -> PathBuf {
self.dir.join("images")
}
/// The same image can be attached in several places, and is stored once.
pub fn deleting_images<T>(
&self,
store: &Store,
of: ImagesOf,
delete: impl FnOnce() -> store::Result<T>,
) -> store::Result<T> {
let files = store.image_files(of)?;
let deleted = delete()?;
for file in store.unused_images(files)? {
let _ = fs::remove_file(self.images().join(file));
}
Ok(deleted)
}
pub fn lock_exclusive(&self) -> Result<Option<File>> {
let lock = self.lock_file()?;
match lock.lock() {
Ok(()) => Ok(Some(lock)),
Err(e) if unsupported(&e) => Ok(None),
Err(e) => Err(e).context("cannot lock kanzo.lock"),
}
}
fn lock_file(&self) -> Result<File> {
let path = self.dir.join("kanzo.lock");
OpenOptions::new()
.create(true)
.truncate(false)
.write(true)
.open(&path)
.with_context(|| format!("cannot open {}", path.display()))
}
}
/// Anyone who can comment can write a file link, so opening one must never run anything. Only an
/// editor, then, not a generic opener: `open` with no flags runs a `.command` file, `xdg-open` a
/// `.desktop` file, and Windows `start` a program.
fn editor_command(editor: Option<&Path>, file: &Path) -> Result<Command, String> {
if !file.is_absolute() || !file.is_file() {
return Err(format!("{} is not a file on this computer", file.display()));
}
let mut cmd = match editor {
Some(editor) => Command::new(editor),
None if cfg!(target_os = "macos") => {
let mut open = Command::new("open");
open.arg("-t");
open
}
None => return Err("set `editor` in config.toml to open files, as the full path of your editor".into()),
};
cmd.arg(file);
Ok(cmd)
}
/// Some filesystems (exFAT, network shares) have no file locks: Kanzo goes on without.
fn unsupported(e: &io::Error) -> bool {
#[cfg(unix)]
if matches!(e.raw_os_error(), Some(libc::ENOTSUP | libc::ENOLCK)) {
return true;
}
e.kind() == io::ErrorKind::Unsupported
}
fn write_if_missing(path: &Path, contents: &str) -> Result<()> {
if !path.exists() {
fs::write(path, contents).with_context(|| format!("cannot write {}", path.display()))?;
}
Ok(())
}
pub fn output(cmd: &mut Command) -> Result<String> {
let line: Vec<_> = std::iter::once(cmd.get_program()).chain(cmd.get_args()).map(|a| a.to_string_lossy()).collect();
let line = line.join(" ");
let out = cmd
.output()
.with_context(|| format!("cannot run {}; is it installed?", line.split(' ').next().unwrap_or_default()))?;
if !out.status.success() {
bail!("{line} failed: {}", String::from_utf8_lossy(&out.stderr).trim());
}
Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
}
pub fn hostname() -> String {
let name = |cmd: &mut Command| output(cmd).ok().filter(|n| !n.is_empty());
name(Command::new("scutil").args(["--get", "ComputerName"]))
.or_else(|| name(&mut Command::new("hostname")))
.unwrap_or_else(|| "unknown".into())
}
pub fn write_whole(path: &Path, bytes: &[u8]) -> io::Result<()> {
if let Some(dir) = path.parent() {
fs::create_dir_all(dir)?;
}
// A half-written file never takes the real name.
let partial = path.with_extension("part");
fs::write(&partial, bytes)?;
fs::rename(&partial, path)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn first_open_creates_files() {
let tmp = tempfile::tempdir().unwrap();
let dir = tmp.path().join("data");
let home = Home::open(dir.clone()).unwrap();
assert!(dir.join("config.toml").exists());
assert!(dir.join(".gitignore").exists());
assert!(dir.join("kanzo.db").exists());
assert_eq!(home.config.port, DEFAULT_PORT);
assert!(home.config.mcp_http);
assert!(home.config.listen.is_loopback());
}
#[test]
fn statuses_from_before_0_2_are_ignored() {
let tmp = tempfile::tempdir().unwrap();
fs::write(tmp.path().join("config.toml"), "statuses = [\"todo\", \"doing\", \"done\"]\n").unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
assert_eq!(home.store().unwrap().statuses(), ["todo", "doing", "review", "done"]);
}
#[test]
fn waits_for_sync_then_reports_busy() {
let tmp = tempfile::tempdir().unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
let lock = home.lock_exclusive().unwrap();
assert!(matches!(home.store(), Err(store::Error::Busy(_))));
let waiting = std::thread::spawn({
let home = home.clone();
move || home.store().map(|s| s.statuses().len())
});
std::thread::sleep(Duration::from_millis(200));
assert!(!waiting.is_finished());
drop(lock);
assert_eq!(waiting.join().unwrap().unwrap(), 4);
}
#[test]
fn a_file_link_opens_in_an_editor_and_only_a_file() {
let tmp = tempfile::tempdir().unwrap();
let file = tmp.path().join("run.command");
fs::write(&file, "").unwrap();
let args = |cmd: &Command| cmd.get_args().map(|a| a.to_owned()).collect::<Vec<_>>();
let cmd = editor_command(Some(Path::new("/bin/cursor")), &file).unwrap();
assert_eq!(cmd.get_program(), "/bin/cursor");
assert_eq!(args(&cmd), [file.as_os_str()]);
if cfg!(target_os = "macos") {
let cmd = editor_command(None, &file).unwrap();
assert_eq!(cmd.get_program(), "open");
assert_eq!(args(&cmd), [std::ffi::OsStr::new("-t"), file.as_os_str()]);
} else {
assert!(editor_command(None, &file).is_err_and(|e| e.contains("editor")));
}
let editor = Some(Path::new("/bin/cursor"));
for bad in [Path::new("run.command"), tmp.path(), &tmp.path().join("missing")] {
assert!(editor_command(editor, bad).is_err(), "{}", bad.display());
}
}
#[test]
fn open_waits_for_a_pull_to_put_config_toml_back() {
let tmp = tempfile::tempdir().unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
let config = home.dir.join("config.toml");
let lock = home.lock_exclusive().unwrap();
fs::write(&config, "listen = \"0.0.0.0\"\n").unwrap();
let opening = std::thread::spawn({
let dir = home.dir.clone();
move || Home::open(dir)
});
std::thread::sleep(Duration::from_millis(200));
assert!(!opening.is_finished());
fs::write(&config, "listen = \"127.0.0.1\"\n").unwrap();
drop(lock);
assert!(opening.join().unwrap().unwrap().config.listen.is_loopback());
}
#[test]
fn open_restores_a_config_toml_left_aside_by_a_crash() {
let tmp = tempfile::tempdir().unwrap();
fs::write(tmp.path().join("config.toml.bak"), "listen = \"0.0.0.0\"\n").unwrap();
// What git had pulled when the sync died.
fs::write(tmp.path().join("config.toml"), "port = 4300\n").unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
assert!(!home.config.listen.is_loopback());
assert_eq!(home.config.port, DEFAULT_PORT);
assert!(!home.config_aside().exists());
}
#[test]
fn no_lock_only_when_unsupported() {
assert!(unsupported(&io::Error::from(io::ErrorKind::Unsupported)));
#[cfg(unix)]
assert!(unsupported(&io::Error::from_raw_os_error(libc::ENOLCK)));
assert!(!unsupported(&io::Error::from(io::ErrorKind::PermissionDenied)));
}
}