Skip to content
kikimimi

Development

Workspace layout

Section titled “Workspace layout”

A Cargo workspace plus one Vite/React SPA:

crates/
  schema           kikimimi.v1 event schema
  spool            fail-open on-disk queue the hook shim writes to
  otlp             OTLP/HTTP receiver (Claude Code's OTel export)
  adapter-claude   Claude Code hook payload -> Event
  adapter-codex    Codex rollout session log tailer -> Event
  sink             file / cloud / BYO S3 sinks
  cli              the kikimimi/kkmm binary (hook, agent, query, login, sink, repos, ...)
  cloud            kikimimi cloud: the kikimimi-cloud binary (Postgres, GitHub OAuth, /v1 + /web APIs)
web/               Vite + React SPA — embedded by both `kikimimi agent` (local web UI)
                   and kikimimi cloud (kikimimi.dev), same codebase either way

Build and test

Section titled “Build and test”
Terminal window
cargo build --workspace
cargo test --workspace

Two things cargo test --workspace needs on PATH/reachable, or the relevant tests fail:

  • Postgres, for crates/cloud’s tests. They default to postgres://postgres:guru-dev@127.0.0.1:5433/guru if DATABASE_URL isn’t set — point DATABASE_URL at your own instance instead if you’d rather not run one on port 5433.
  • The duckdb CLI, for crates/cli’s query tests (kikimimi query shells out to it, same as it does at runtime).

The web UI has its own build, independent of cargo:

Terminal window
cd web && npm run build   # tsc --noEmit && vite build

Running your own cloud

Section titled “Running your own cloud”

kikimimi cloud (crate crates/cloud, binary kikimimi-cloud) is a self-contained server: it runs its own Postgres migrations on startup — connecting is enough, nothing separate to invoke first. Configuration is environment variables, the ones you’ll actually need to set:

  • DATABASE_URL — Postgres connection string (superuser; the server also opens a second, RLS-scoped pool internally).
  • BIND_ADDR — defaults to 127.0.0.1:8787.
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET — GitHub OAuth app credentials. Without both set, GitHub sign-in 503s.
  • KIKIMIMI_INVITE_CODE — enables a legacy email+invite-code login as a bootstrap path when you haven’t wired up a GitHub OAuth app yet.

Point a device at it (see Teams):

Terminal window
kikimimi login --endpoint https://kikimimi.your-company.internal

The repo’s own Dockerfile and fly.toml are the example deploy: cargo build --release -p kikimimi-cloud, a slim runtime image, BIND_ADDR=0.0.0.0:8787, deployed to Fly.io. Neither is required — they’re just what’s checked in and actually used to run kikimimi.dev.

The docs site

Section titled “The docs site”

This site (docs/, Astro + Starlight) builds as a static website and deploys independently to the kikimimi-site Fly app on a push to main that touches docs/**. The LP is at kikimimi.dev and this manual lives under /kikimimi/. GitHub Pages is no longer used.

Terminal window
cd docs && npm run dev      # local preview, live reload
cd docs && npm run build    # astro build, same as the CI deploy step

Contributing

Section titled “Contributing”

Built in the open — issues and PRs welcome on github.com/isamisushi/kikimimi.

License

Section titled “License”

Apache-2.0 for the agent daemon, CLI, adapters, kikimimi.v1 schema, detection SQL, local web UI and docs — everything a user installs.

The hosted cloud service under crates/cloud/ is FSL-1.1-Apache-2.0: free to read, run and modify for your own use (including commercially), but not to offer as a competing hosted product. Each release of that directory converts to Apache-2.0 two years after it ships.