Skip to content

Quick start

Five minutes to a working LOKUST session on your Mac.

Prerequisites

  • macOS (Apple silicon or Intel)
  • Rust toolchain (rustup install stable)
  • ANTHROPIC_API_KEY in your environment (for agent coordination)
  • Python 3.10+ (for the shell capture scripts)

Build

cd lokust-platform/session-vm
cargo build --release -p lokust-daemon -p lokust-cli

Binaries land at target/release/lokustd and target/release/lokust.

Start the daemon

./target/release/lokustd &

You should see:

lokustd running on http://127.0.0.1:7700
sessions dir: /Users/<you>/.lokust/sessions

Create and run a session

# In a project directory
lokust init

# Run all 5 phases (architect → security → integration → testing → documentation)
lokust session run

# Watch status
lokust session status

Each phase calls Claude via the agent-runtime host import and streams output to disk. A full 5-agent run is roughly 3–6 minutes and 40–60 K tokens.

Pause and export

# Pause mid-run
lokust session pause

# An auto-exported .lok file lands in the current directory:
#   session-<id>.lok

The .lok file is under 50 KB for a typical session. It carries all completed agent outputs, metadata, and the workflow definition.

Import on another device

Transfer the .lok file (AirDrop, email, URL). On the target device:

lokustd &
lokust session import <file>.lok
lokust session run    # picks up from the first incomplete phase

Completed agents stay completed. Remaining phases run with full prior context. Same session, different device.

Also capture the shell

To grab your terminal context (cwd, env, redacted history, Claude Code conversations):

./scripts/lokust-shell-snapshot --bundle ghostty.lok
./scripts/lokust-shell-restore ghostty.lok          # on another Mac

With --bundle the .lok embeds the full ~/.claude/projects/<slot>/ directory. Restoring places it on the target machine so Claude Code picks up the conversation automatically.

Persistent shell with tmux

./scripts/lokust-tmux new myshell       # create session
./scripts/lokust-tmux attach myshell    # work in it
# detach with Ctrl-B d — shell keeps running
./scripts/lokust-tmux export myshell    # snapshot to .lok

Next