README
¶
akari
akari collects the local session logs of coding agents (Claude Code, Codex, and pi) on a self-hosted server: a searchable history of every session across your machines, grouped by the git project they ran in, with every token priced. It is an explicit client/server split. Thin clients push raw session bytes; the server parses, prices, and serves a web UI and a read-only MCP endpoint. Because the client keeps no derived state, a parser improvement reaches old sessions by re-parsing on the server, with nothing re-uploaded.
Documentation
The full user guide lives on the running server itself, themed to match the UI:
open /guide on the main instance, and
every akari server serves its own copy at /guide. The guide is written for
agents as much as humans: append .md to any page URL for its raw Markdown,
fetch /llms-full.txt for the whole
guide in one request, and /llms.txt for
the machine-readable index. The source lives in
internal/guide/content.
Install
Prebuilt, checksum-verified binaries are published for each release. Each script
downloads the archive for your OS and architecture, verifies it against the
release SHA256SUMS, and installs the binary. Set AKARI_VERSION (for example
v0.1.0) to pin a version instead of taking the latest.
Client, Linux and macOS:
curl -fsSL https://raw.githubusercontent.com/jssblck/akari/main/scripts/install.sh | sh
Client, Windows (PowerShell):
irm https://raw.githubusercontent.com/jssblck/akari/main/scripts/install.ps1 | iex
Server, Linux:
curl -fsSL https://raw.githubusercontent.com/jssblck/akari/main/scripts/install-server.sh | sh
Add -s -- --systemd to the server command to also install a managed systemd
service, a dedicated akari user, and an environment file at
/etc/akari/server.env. The client updates itself in place with akari update.
Upgrade the server by deploying a versioned container image or package, or by
replacing the managed binary and restarting its service supervisor. See
docs/releases.md for the asset list and upgrade options.
Quick start
After installing, mint an ingest token on the server's account page, then point the client at your server and start pushing:
akari login --server https://akari.example.com --token <ingest-token>
akari sync # one-shot upload of everything new
akari daemon start # keep uploading in the background
The getting-started chapter of the guide covers the rest.
No server yet? docker compose up -d --build with the bundled compose file
stands one up; the
self-hosting chapter covers
real deployments.
Development
Orientation for agents and contributors is AGENTS.md. The development loop (build, tests, eph, seed data) is docs/development.md, the engineering design is docs/DESIGN.md, and the visual design system is DESIGN.md. Contributions follow CONTRIBUTING.md.
License
akari follows the repository license split described in NOTICE:
runtime software is AGPL-3.0-or-later, while documentation and creative content
are CC-BY-SA-4.0 unless a file says otherwise. See also the
security policy, the contributing guide, and
the code of conduct.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
akari
command
Command akari is the session-backup client: it discovers agent sessions, resolves each to its git project, and pushes new bytes to an akari server.
|
Command akari is the session-backup client: it discovers agent sessions, resolves each to its git project, and pushes new bytes to an akari server. |
|
akari-server
command
Command akari-server ingests, stores, parses, and serves agent sessions.
|
Command akari-server ingests, stores, parses, and serves agent sessions. |
|
internal
|
|
|
casenc
Package casenc encodes tool bodies for the content-addressed store.
|
Package casenc encodes tool bodies for the content-addressed store. |
|
client/daemon
Package daemon runs the watch loop as a background process and enforces a single running instance per machine.
|
Package daemon runs the watch loop as a background process and enforces a single running instance per machine. |
|
client/discover
Package discover enumerates agent session files from each agent's known roots.
|
Package discover enumerates agent session files from each agent's known roots. |
|
client/resolve
Package resolve turns a discovered session file into the project it belongs to.
|
Package resolve turns a discovered session file into the project it belongs to. |
|
client/syncer
Package syncer combines resolution and upload for a single session file.
|
Package syncer combines resolution and upload for a single session file. |
|
client/upload
Package upload drives the ingest protocol from the client side, statelessly.
|
Package upload drives the ingest protocol from the client side, statelessly. |
|
client/watch
Package watch keeps session files synced continuously.
|
Package watch keeps session files synced continuously. |
|
config
Package config loads akari-server configuration.
|
Package config loads akari-server configuration. |
|
devseed
Package devseed fills a local akari server with realistic example data for development.
|
Package devseed fills a local akari server with realistic example data for development. |
|
durationfmt
Package durationfmt formats a session's wall-clock span for display.
|
Package durationfmt formats a session's wall-clock span for display. |
|
gitremote
Package gitremote canonicalizes a git origin URL into akari's project key: a stable "authority/owner/.../repo" string that is identical across machines, clone URLs (ssh, https, scp-like), and worktrees.
|
Package gitremote canonicalizes a git origin URL into akari's project key: a stable "authority/owner/.../repo" string that is identical across machines, clone URLs (ssh, https, scp-like), and worktrees. |
|
guide
Package guide is akari's self-hosted user guide: the Markdown chapters, the ordered chapter registry, and the rendering that turns them into the HTML the web layer shows and the plain-text forms an agent ingests.
|
Package guide is akari's self-hosted user guide: the Markdown chapters, the ordered chapter registry, and the rendering that turns them into the HTML the web layer shows and the plain-text forms an agent ingests. |
|
parser
Package parser turns the raw bytes of an agent session file into akari's normalized projection: ordered messages, tool calls, and token usage.
|
Package parser turns the raw bytes of an agent session file into akari's normalized projection: ordered messages, tool calls, and token usage. |
|
pricing
Package pricing computes session cost from a model rate table compiled into the binary.
|
Package pricing computes session cost from a model rate table compiled into the binary. |
|
quality
Package quality turns a session's behavioral signals into an outcome classification and a 0-100 quality score with an A-F grade.
|
Package quality turns a session's behavioral signals into an outcome classification and a 0-100 quality score with an A-F grade. |
|
selfupdate
Package selfupdate resolves and downloads akari client releases from GitHub so the client can update itself in place.
|
Package selfupdate resolves and downloads akari client releases from GitHub so the client can update itself in place. |
|
server/auth
Package auth holds akari-server's credential primitives: argon2id password hashing, opaque token and id generation, and token hashing.
|
Package auth holds akari-server's credential primitives: argon2id password hashing, opaque token and id generation, and token hashing. |
|
server/httpapi
Package httpapi wires akari-server's HTTP surface: authentication, account and token management, and the session ingest protocol.
|
Package httpapi wires akari-server's HTTP surface: authentication, account and token management, and the session ingest protocol. |
|
server/mcpserver
Package mcpserver builds the read-only Model Context Protocol surface akari exposes to coding agents.
|
Package mcpserver builds the read-only Model Context Protocol surface akari exposes to coding agents. |
|
server/ogimage
Package ogimage renders the Open Graph preview card for a published usage overview: a 1200x630 PNG a link unfurler (Slack, Discord, iMessage, and the like) shows when someone shares a /u/<username> link.
|
Package ogimage renders the Open Graph preview card for a published usage overview: a 1200x630 PNG a link unfurler (Slack, Discord, iMessage, and the like) shows when someone shares a /u/<username> link. |
|
server/parse
Package parse is the server-side pipeline that turns a session's stored raw bytes into the queryable projection.
|
Package parse is the server-side pipeline that turns a session's stored raw bytes into the queryable projection. |
|
server/requestbudget
Package requestbudget bounds expensive request work across an akari process.
|
Package requestbudget bounds expensive request work across an akari process. |
|
server/store
Package store is the akari-server data layer: a Postgres connection pool, the startup migration runner, and the query methods the rest of the server uses.
|
Package store is the akari-server data layer: a Postgres connection pool, the startup migration runner, and the query methods the rest of the server uses. |
|
server/storetest
Package storetest provisions throwaway, fully isolated Postgres databases for the akari server's integration tests.
|
Package storetest provisions throwaway, fully isolated Postgres databases for the akari server's integration tests. |
|
server/web
Package web holds akari's server-rendered UI: templ templates and the small view-model helpers they use.
|
Package web holds akari's server-rendered UI: templ templates and the small view-model helpers they use. |
|
shutdown
Package shutdown turns the first interrupt into a graceful stop and the second into an immediate exit.
|
Package shutdown turns the first interrupt into a graceful stop and the second into an immediate exit. |
|
version
Package version reports the build version of the akari binaries.
|
Package version reports the build version of the akari binaries. |
|
Package migrations embeds the forward-only SQL migration files so the server can apply them on startup without shipping the .sql files separately.
|
Package migrations embeds the forward-only SQL migration files so the server can apply them on startup without shipping the .sql files separately. |