akm-cli/docs/maintainers/local-development.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

# Local Development

Use an explicit launcher for each kind of contributor check. This keeps live
source, build output, packed-package behavior, and the machine-wide `akm`
installation from being mistaken for one another.

The npm package requires Node.js >= 22 and npm. A working Bun >= 1.0 is optional
for the installed launcher and remains the repository's primary development and
test runtime. The standalone binaries are runtime-free.

## Live Source

Run the working tree directly for the normal edit-test loop:

```bash
bun src/cli.ts search "deploy"
bun src/cli.ts task doctor
```

This executes current uncommitted source. Tests that spawn the CLI should use
the same explicit `bun src/cli.ts` form with the repository as their working
directory rather than resolving `akm` from `PATH`.

## Built Launcher

Build first, then invoke the package launcher from `dist/`:

```bash
bun run build
node dist/akm search "deploy"
node dist/akm task doctor
```

This checks generated imports, copied assets, and launcher behavior while still
keeping the invocation tied to this checkout. `node dist/akm` is portable across
Windows, macOS, and Linux; on POSIX systems the executable `./dist/akm` form is
also available.

## Isolated Package Acceptance

Run the repository's package acceptance command. It builds and packs the package,
installs it under an isolated temporary prefix, and exercises that installed
launcher without replacing the machine's global `akm`:

```bash
bun run test:package
```

The command builds, packs, installs under a temporary npm prefix, and checks the
installed launchers. It does not run setup or test application-state isolation.

## Intentional Global Checkout Install

Only install the checkout globally when you deliberately want the machine-wide
`akm` command to resolve to this checkout's package:

```bash
bun run build:install
command -v akm
akm --version
```

This replaces the globally resolved package and can affect agents, shells, and
scheduled tasks that invoke `akm`. Re-run `akm task sync --rebind` only when you
intend existing scheduler entries to capture the new installed runtime, then
verify with `akm task doctor`.

## Transitional Machine-Local Wrapper

Some development machines still have a historical machine-local wrapper. Leave
that file untouched, but treat it as transitional: do not document wrapper
modes, depend on it in tests, or use it to choose between source and package
behavior. Invoke `bun src/cli.ts`, `node dist/akm`, or `bun run test:package`
explicitly instead.

## Inspecting a Live Database

`state.db`, `logs.db`, and `index.db` are WAL-mode SQLite databases that akm
(or a scheduled task) may be writing at any moment. Open a live one only with
`sqlite3 -readonly`:

```bash
sqlite3 -readonly ~/.local/share/akm/state.db "PRAGMA integrity_check;"
sqlite3 -readonly ~/.local/share/akm/state.db ".backup /tmp/state-snapshot.db"
```

Do not open a live akm database with a plain (read-write) `sqlite3`
connection, even just to run `.backup`. Through 0.9.17 an akm process could
silently lose its SQLite file locks (copying the database file inside a
process that holds it open drops them). An older `sqlite3` (< 3.51, and
Python's `sqlite3` module on many hosts) opened read-write at that moment
sees no other reader, takes an exclusive lock when it closes, and deletes the
`-wal`/`-shm` files akm is still using: that produced a `state.db` with
colliding rowids and stale index entries. `-readonly` avoids the whole class
of risk by never taking a write connection.

## Verification

Use focused tests while iterating, then the repository gates before pushing:

```bash
bun test tests/<focused-file>.test.ts
bun run check:changed
bun run check
```

For eval scripts that accept `AKM_BIN`, point it at the exact launcher under
test rather than relying on `PATH`.