Praxis CLI

The Kolaborate coding-first AI assistant for the terminal. Praxis pairs a full coding agent (read/write/edit/grep/find/ls/bash) with planning, persistent memory, MCP integration, project-rule loading, code review, and admin workflows — usable from the terminal (Ink UI), as a one-shot command, via WhatsApp, or as a long-running daemon.

Praxis is for every Kolaborator — engineers, designers, ops, and admins — not just internal tooling. It's billed per session in KoloCoins.

Bun-required. Praxis ships a Bun-targeted bundle so the daemon, MCP servers, and Ink UI all "just work". Bun ≥ 1.0 must be installed on the target machine.

Installation

# Install Bun first (one-time)
curl -fsSL https://bun.sh/install | bash

# Then install Praxis globally
npm install -g @kolaborate/praxis-cli
# or
bun install -g @kolaborate/praxis-cli

# Verify
praxis --version

Quick Start

# 1. One-time configuration wizard
praxis config init

# 2. Sanity-check config + harness + auth
praxis config show
praxis harness check

# 3. Start working
praxis interactive             # full Ink-based REPL
praxis chat "explain this repo's auth flow"
praxis review --staged         # AI code review on staged files

You will need:

• Convex deployment URL — the same NEXT_PUBLIC_CONVEX_URL you use in any monorepo .env.local, or grab it from the Convex dashboard.
• Firebase UID — the firebaseId field on your row in the Convex users table. Easiest path: log into the Kolaborate web app once, then read it from the Convex dashboard.
• Either an OpenRouter API key (for the default kola harness, billed in KoloCoins) or the Google Gemini CLI installed (for the optional gemini fallback harness).

All can be set through praxis config init or as environment variables (see Environment Variables).

What Praxis can do

The active harness (kola by default) runs an agent loop with the following tools registered out of the box. Any of them can be invoked through natural language in praxis chat / praxis interactive / WhatsApp.

| Tool group | Capabilities | | --- | --- | | Coding (via pi-coding-agent) | read_file, write_file, edit_file, grep, find, ls, bash — full file-system + shell access in your current working directory. | | Planning | planning_mode — switch between plan (read-only drafting) and ask (normal interactive) so you can think before changes. | | Project rules | load_project_rules — auto-loads AGENTS.md, .agent/AGENTS.md, CLAUDE.md, .cursorrules from the repo so the agent obeys your standards. | | Memory | memory_manager — save / read / list / delete namespaced facts that persist across sessions. | | Admin tasks | admin_tasks — list / create / update / start / complete / search / stats against the Kolaborate admin tasks system. | | Health check | health_check — runs bun run typecheck/build, tsc --noEmit, or cargo check to verify changes don't break the project. | | Interactive | ask_user_question — agent can pause and ask you to confirm before risky actions. | | MCP | Any MCP server you register via praxis mcp add is exposed as additional tools (e.g., GitHub, Linear, Postgres, custom internal servers). |

Permission modes

The engine runs in ask mode by default — it will prompt before destructive actions (writes, edits, bash). Switch with the planning_mode tool or via the !harness/permission menu in interactive mode.

Commands

Interactive (praxis interactive)

A persistent Ink-based REPL with conversation history, status bar, and live tool indicators:

praxis interactive                       # default session
praxis interactive --session feature-x   # named session, persists across restarts

Meta-commands inside the REPL:

| Command | Action | | ----------------- | -------------------------- | | !help | Show all commands | | !clear | Clear conversation history | | !session <name> | Switch to a named session | | !sessions | List saved sessions | | !history | View recent messages | | !harness <name> | Switch AI harness | | !harnesses | List registered harnesses | | !delete <name> | Delete a saved session | | exit / quit | Leave interactive mode |

One-shot chat (praxis chat)

praxis chat "summarize what changed in apps/marketplace this week"
praxis chat "draft a Convex mutation that closes stale support tickets"
praxis chat "what tests cover the auth resolver?"

Code review (praxis review)

Runs a structured AI code review against the current repo. Automatically pulls CLAUDE.md for project context and emits findings as FINDING: SEVERITY | file:line | message.

praxis review path/to/file.ts          # review a specific file
praxis review --staged                 # review currently staged files
praxis review --since main             # review files changed since git ref

WhatsApp adapter (praxis whatsapp)

Talk to Praxis from your phone via WhatsApp self-chat:

praxis whatsapp                  # foreground (interactive QR scan)
praxis whatsapp --daemon         # background daemon

Scan the QR with WhatsApp → Linked Devices. After pairing, send messages to yourself (self-chat) and Praxis will respond. All other senders are silently ignored — your account can never be hijacked into responding to strangers.

Daemon mode (praxis start / stop / status)

Run Praxis as a long-lived background process (also auto-launches WhatsApp if enabled):

praxis start                     # start daemon
praxis status                    # show daemon status, active harness, registered tools
praxis stop                      # stop daemon
tail -f ~/.praxis/daemon.log     # follow logs

Quick task shortcuts

Skip the LLM and hit the admin-tasks tool directly — useful for scripts and muscle memory:

praxis tasks list
praxis tasks list --status pending --date 2026-05-06
praxis tasks add "Deploy API v2" --priority high --category Engineering
praxis tasks done <task-id> --notes "Deployed via CI"
praxis tasks search "deploy"

Sessions (praxis sessions)

praxis sessions list
praxis sessions delete old-session

Harness management (praxis harness)

Praxis ships with two harnesses: kola (default — OpenRouter via the Vercel AI SDK, billed in KoloCoins through the Kolaborate backend) and gemini (Google Gemini CLI fallback, no KoloCoins charge).

praxis harness list              # list registered harnesses
praxis harness check             # verify current harness is ready
praxis harness switch gemini     # change default harness

MCP server management (praxis mcp)

Add third-party MCP servers; they're exposed to the active harness as extra tools. Server config lives at ~/.praxis/mcp.json.

praxis mcp list
praxis mcp add everything npx -y @modelcontextprotocol/server-everything
praxis mcp add github npx -y @modelcontextprotocol/server-github
praxis mcp remove everything

Configuration (praxis config)

Resolved in priority order: environment variables > config file > defaults.

praxis config show       # display config + source indicators
praxis config init       # interactive setup wizard
praxis config set --url <convex>  --firebase <uid>  --kola-api-key <key>
praxis config set --openrouter-api-key <key>
praxis config set --kola-model deepseek/deepseek-chat-v4-5
praxis config set --gemini-path /opt/homebrew/bin/gemini --gemini-model gemini-2.5-flash

Environment Variables

| Variable | Required | Description | | ------------------------ | -------- | --------------------------------------------------------------- | | PRAXIS_CONVEX_URL | Yes | Convex deployment URL | | PRAXIS_FIREBASE_UID | Yes | Your Firebase UID (the firebaseId on your Convex user record) | | OPENROUTER_API_KEY | Yes* | OpenRouter API key — used by the default kola harness | | KOLA_API_KEY | No | Kolaborate agent API key (for backend audit/RBAC) | | PRAXIS_WEB_URL | No | Override the Praxis web LLM proxy endpoint | | NEXT_PUBLIC_CONVEX_URL | Fallback | Also accepted for Convex URL (monorepo convenience) |

* Not required if you've switched to the gemini harness via praxis harness switch gemini.

How the agent loop works

User message
  → ContextBuilder loads system prompt + tool descriptions + AGENTS.md/CLAUDE.md + history
  → Active harness (kola | gemini) plans an action
  → Engine executes the chosen tool (read, write, bash, plan, memory, mcp.<server>.<tool>, …)
  → Result is fed back into the harness (max-loop guard prevents infinite cycles)
  → Final response streamed back to the adapter (CLI, WhatsApp, daemon)
  → Persisted to JSONL session history

Sessions running on the kola harness are charged in KoloCoins on the Kolaborate backend (one charge per session, not per round).

Data storage

All runtime state lives under ~/.praxis/:

~/.praxis/
  config.json          User configuration (env vars take priority)
  mcp.json             Configured MCP servers
  sessions/            JSONL conversation logs per session
  whatsapp-auth/       Baileys session credentials (after first QR scan)
  daemon.log           Daemon stdout/stderr
  praxis.pid           PID file when daemon is running

Troubleshooting

praxis: command not found after install

Make sure Bun is on your PATH — the npm bin is a Bun script:

which bun
bun --version    # should be ≥ 1.0

If which bun returns nothing, install it: curl -fsSL https://bun.sh/install | bash and reopen your shell.

"OPENROUTER_API_KEY not set"

The default kola harness needs an OpenRouter key. Either set the env var or run praxis config set --openrouter-api-key <key>. Switch to Gemini with praxis harness switch gemini if you'd rather use Google's CLI.

"User with Firebase UID … not found in Convex"

Your PRAXIS_FIREBASE_UID doesn't match a row in the Convex users table. Confirm:

1. You're pointing at the right Convex deployment (praxis config show).
2. Your Firebase UID matches the firebaseId field on your Convex user.
3. You've signed into a Kolaborate web app at least once (provisions the Convex user).

"Gemini CLI binary not found in PATH"

Only matters if you've switched to the gemini harness. Install via npm install -g @google/gemini-cli or brew install gemini-cli, then point Praxis at it with praxis config set --gemini-path $(which gemini).

WhatsApp QR doesn't appear

Make sure you're in foreground mode (praxis whatsapp, not praxis whatsapp --daemon). The QR only renders in an interactive terminal.

Daemon dies immediately

cat ~/.praxis/daemon.log

Common causes: missing env vars, auth failure, harness unavailable.

Local development

For monorepo contributors hacking on Praxis itself:

cd apps/praxis-cli
cp .env.example .env
bun install
bun run bin/praxis.ts --help          # run from source
bun run typecheck
bun run build:npm                      # produce dist/praxis.js (Bun-target bundle)

License & Intellectual Property

Proprietary — © 2024-2026 Kolaborate Platforms Ltd. All rights reserved.

Praxis is proprietary software of Kolaborate Platforms Ltd. The package is published to npm only so authorized Kolaborators, contractors, and partners can install it with npm install -g @kolaborate/praxis-cli — it is not an open-source release. Use is governed by the terms in the LICENSE file and any separate written agreement with Kolaborate.

You may install and run Praxis to interact with Kolaborate services using your own credentials. You may not redistribute, fork, modify, reverse-engineer, or use this software to build a competing product. See LICENSE for full terms. Licensing inquiries: [email protected].