Type what you want. Kaamurai does the work.

An agent-first, local-first operating system project built on Arch Linux.

What is Kaamurai OS?

Kaamurai OS is an experimental operating-system project where the user describes an outcome in plain language and a local agent turns it into safe, inspectable system work.

The intended interaction is simple:

User states an outcome
        -> Kaamurai gathers local context
        -> Kaamurai prepares a structured plan
        -> Policy validates permissions and risk
        -> Sensitive work waits for approval
        -> The executor runs and verifies the result

The name combines kaam (work) with samurai (a disciplined executor). The product is Kaamurai OS, the agent is Kaamurai, and the user command is kaamurai.

Current Reality

Kaamurai OS is an early alpha, not a finished distribution. The repository now contains a small working vertical slice of the agent stack plus a restored ArchISO live profile.

Area	Status	What exists today
kaamurai-indexd	Implemented prototype	SQLite metadata scanner, constrained UNIX socket queries, and tests
ArchISO profile	Source ready	Kaamurai-branded BIOS/UEFI/PXE profile and reproducible build script
kaamurai-agent	Bootstrap implemented	Deterministic planner plus optional local-model adapter for four narrow read-only outcomes
kaamurai-execd	Bootstrap implemented	Policy-checked read-only handlers, approval gate, and content-safe audit log
kaamurai command	Bootstrap implemented	Plan display, JSON output, approvals, execution, and clear exit codes
Installer	Skeleton only	Opens safely and refuses to modify disks

The implemented command loop currently supports these outcomes:

kaamurai --plan-only "find pacman.conf"
kaamurai "check system health"
kaamurai "show large files in /var/log"
kaamurai "preview /etc/pacman.conf"

This slice is intentionally read-only. Package management, service changes, workspace setup, and other system mutations are not implemented and will be rejected.

The optional local-model adapter is now available behind the same contract. Set KAAMURAI_MODEL to an installed Ollama-compatible model name and use --agent local; --agent auto keeps deterministic planning unless a model is configured. Model output is parsed as structured JSON and validated before it can reach the executor.

Architecture

flowchart LR
    U["User outcome"] --> CLI["kaamurai"]
    CLI --> AGENT["kaamurai-agent"]
    INDEX["kaamurai-indexd"] --> AGENT
    AGENT --> PLAN["Structured plan"]
    PLAN --> POLICY["Schema and policy validation"]
    POLICY --> APPROVAL{"Approval required?"}
    APPROVAL -->|Yes| USER["User review"]
    APPROVAL -->|No| EXEC["kaamurai-execd"]
    USER -->|Approved| EXEC
    EXEC --> RESULT["Verified result and recovery log"]

Loading

The planner is never the executor. Generated plans cross an explicit trust boundary and must pass schema, permission, risk, and recovery checks before they can affect the system.

Read the complete architecture, command flow, and safety model.

Repository Layout

kaamurai-os/
  assets/brand/             Brand marks and boot-splash source
  core/
    kaamurai_agent/         Deterministic bootstrap planner
    kaamurai_cli/           User command and index client
    kaamurai_execd/         Read-only controlled executor
    kaamurai_protocol/      Shared plan models and policy
    kaamurai_indexd/        Working filesystem indexer prototype
  docs/                     Architecture, safety, vision, and roadmap
  iso/
    kaamurai/               ArchISO live and rescue profile
  models/                   Local model guidance
  os/
    installer/              Installer planning
    services/               systemd service definitions
  scripts/
    build-iso.sh            Reproducible ISO build entrypoint

Try the Working Command Loop

Kaamurai currently uses only the Python standard library and requires Python 3.10 or newer.

git clone https://github.com/AnuranjanJain/kaamurai-os.git
cd kaamurai-os
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

kaamurai --plan-only "find pacman.conf"
kaamurai "check system health"

To enable indexed file queries on Linux, start the daemon in one terminal:

mkdir -p .state
export KAAMURAI_INDEXD_DB="$PWD/.state/index.db"
export KAAMURAI_INDEXD_SOCKET="$PWD/.state/indexd.sock"
export KAAMURAI_INDEXD_SCAN_ROOTS=/etc
kaamurai-indexd

Then use the same socket from another terminal:

export KAAMURAI_INDEXD_SOCKET="$PWD/.state/indexd.sock"
kaamurai "find pacman.conf"
kaamurai "show large files in /etc"

Run the test suites with:

python -m unittest discover -s tests
python -m unittest discover -s core/kaamurai_indexd/tests

Indexer configuration:

Variable	Default	Purpose
KAAMURAI_INDEXD_DB	/var/lib/kaamurai/index.db	SQLite database path
KAAMURAI_INDEXD_SOCKET	/run/kaamurai/indexd.sock	UNIX socket path
KAAMURAI_INDEXD_SCAN_ROOTS	/etc	os.pathsep-separated scan roots

Build the Live ISO

The ISO must be built on Arch Linux with the archiso package installed:

sudo pacman -S --needed archiso
sudo bash scripts/build-iso.sh

The generated image is written to iso/out/kaamurai-<version>-x86_64.iso.

The live environment is suitable for boot and rescue testing. Its installer remains intentionally non-destructive until disk handling, installation, bootloader setup, and recovery have been implemented and tested in disposable virtual machines. See the ISO guide.

Principles

• Outcome first: users describe the result instead of manually composing every command.
• Local first: core context and planning should work without a cloud dependency.
• Visible plans: the system explains intended changes before execution.
• Risk-aware approval: permission and confirmation scale with potential impact.
• Recoverable execution: system changes require logs and a recovery path.
• Useful without the agent: Arch Linux remains usable when Kaamurai services are disabled.

Roadmap

Phase	Focus	Status
0	Vision, architecture, safety, and brand	Complete
1	Live system and installer foundation	In progress
2	Indexing, policy, and read-only execution	In progress - first slice working
3	Desktop environment and command center	Planned
4	Local read-only agent	In progress - model adapter added
5	Controlled agent actions	Planned
6	Recovery validation, polish, and release	Planned

The detailed sequence and acceptance criteria live in Development Phases.

Documentation

• Vision
• Core Principles
• Architecture
• Command Flow
• Safety Model
• Instruction Schema
• Filesystem Index Design
• ISO Build Guide
• Brand Guide
• Changelog

Project Notice

Kaamurai OS is under active development and is not ready for installation as a daily operating system. Do not run unfinished installer or executor components on a machine containing important data.