Pithosai (@pithosai/pithosai)

Multi-role AI CLI for coding and product work: natural-language requests, pluggable models (DeepSeek, OpenRouter, Ollama, Cursor), and role-based prompts stored in SQLite.

| | | |---|---| | Best for | Agent-style coding, multi-role workflows (RD / PM / QA / …), local or cloud models, repeatable prompts from a local database | | Requirements | Node.js ≥ 18.12 and at least one model provider | | License | Proprietary — see License |

Installation

npm install -g @pithosai/pithosai

On a global install, if ~/.pithosai/pithosai.db does not exist, it is created from the bundled schema. Override the path with PITHOSAI_DB_PATH.

Highlights

• DeepSeek V4 — Cost-first deepseek-v4-flash by default; --pro and --reasoner for harder work (details).
• Role shortcuts — rdsai, pmsai, qasai, cosai, mktai, wrsai preset role and model defaults.
• Full-screen TUI — Transcript, tool output, and slash commands (/model, /shell, /list, skills, …).
• Virtual projects — Switch workspaces from the REPL via ~/.pithosai/projects.json (details).
• Plan alignment — /grill-me stress-tests a design one question at a time (details).
• Run modes — agent (full tools), dialog (read-only), plan (writes <slug>-plan.md).
• Local persistence — Tasks and prompts in SQLCipher-backed SQLite; optional pithosai migrate-db from legacy plaintext DBs.
• Skills & email — ClawHub-style skills in-session; heartbeat / email-monitor for IMAP-driven tasks.

Quick start

export DEEPSEEK_API_KEY=sk-...   # or another provider below
cd your-project
pithosai init
pithosai "Describe what you want done"

| Invocation | Behavior | |------------|----------| | pithosai -i | Interactive session with no initial prompt | | pithosai --no-interactive "…" | Single run, then exit | | pithosai -C ./other-dir "…" | Use a different project directory | | /exit or /quit | Leave the REPL (plain exit is sent to the agent) |

Each run prints a short ASCII banner. Prompts load from the local database (default ~/.pithosai/pithosai.db). Optional role overrides live under .pithosai/<role>/ in your project.

Language

Default locale is English. Set per run with --lang, or rely on the shell LANG.

pithosai --lang zh "请解释这个错误"

Supported codes include en, ar, de, es, fr, it, ja, ko, nl, pt, zh, and zh-hant (Traditional Chinese, fixed in 1.0.7). Run pithosai --help for the full list.

Upgrading from v1.0.4 (plaintext database)

From 1.0.5 onward, plaintext databases migrate automatically when encryption is available, or you can run pithosai migrate-db. See CHANGELOG.md section [1.0.5].

Model providers

Configure at least one of the following.

| Provider | Setup | |----------|--------| | DeepSeek | export DEEPSEEK_API_KEY=sk-... | | OpenRouter | export OPENROUTER_API_KEY=sk-or-... | | Ollama (local) | Install Ollama, run a model, then export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1 | | Cursor CLI | Install the Cursor agent, sign in, set e.g. export CURSOR_MODEL=auto, and pass --cursor when needed |

Precedence: DeepSeek → Ollama (OPENAI_LOCAL_API_BASE) → OpenRouter → CURSOR_MODEL / --cursor.

DeepSeek API (V4)

With a native DEEPSEEK_API_KEY, flags map to:

| Your choice | API model id | Typical use | |-------------|----------------|-------------| | Default (no --pro / --reasoner) | deepseek-v4-flash | Cost-efficient daily work | | --pro | deepseek-v4-pro | Harder tasks | | --chat | deepseek-v4-flash | Explicit chat path | | --reasoner | deepseek-v4-pro + reasoning | Longer chain-of-thought |

Legacy ids deepseek-chat and deepseek-reasoner are retired upstream; see DeepSeek API docs. Flash paths disable API “thinking” by default so tool-heavy turns stay stable; --reasoner keeps extended reasoning enabled.

With OpenRouter only, use slugs deepseek/deepseek-v4-flash (default) and deepseek/deepseek-v4-pro (--pro / --reasoner). An OpenRouter regression was fixed in 1.0.8.

Role entrypoints

| Command | Role | Default model | |---------|------|----------------| | rdsai | RD | deepseek-v4-flash (unless --pro / --reasoner) | | pmsai, qasai, cosai, mktai | PM / QA / CO / MKT | flash (--chat) | | wrsai | WR (task mode) | flash; default language zh |

These ship as POSIX shell wrappers next to pithosai.mjs that invoke the same binary with preset flags (1.0.9 / 1.0.10).

Use /model in the REPL to list and switch models interactively.

Commands

| Command | Purpose | |---------|---------| | pithosai | Main CLI: init, migrate-db, interactive agent, task, heartbeat, skills, memorize, … | | rdsai, pmsai, qasai, cosai, mktai, wrsai | Same CLI with a default role | | email-monitor | Heartbeat / email-driven task loop | | render-markdown | Render Markdown in the terminal | | init | Initialize ~/.pithosai/pithosai.db manually |

Project maintenance

| Command | What it does | |---------|----------------| | pithosai init [dir] | Scaffold project, .pithosai/sessions/, settings | | pithosai migrate-db | Legacy plaintext DB → SQLCipher | | pithosai add-role <role> | Add a role to the project | | pithosai task --file <md> | Watch a task file and run tasks | | pithosai memorize --start … --end … -r <role> | Build .pithosai/<role>/memory.md | | pithosai heartbeat / heartbeat --once | Email pipeline (IMAP/SMTP in settings) | | pithosai skills … | Install / list / remove skills | | pithosai shell "cmd" | Run a shell command via the CLI |

Use pithosai --help and pithosai <command> --help for flags such as --timeout, --lang, --role, and --log-path.

Run modes

| Mode | Use case | |------|----------| | agent (default) | Full tools: edit files, run commands, … | | dialog | Answers and read-only tools (no shell tool) | | plan | Writes <slug>-plan.md; read-only tools |

pithosai --mode dialog "Explain this error"
pithosai --mode plan "Outline the next sprint"

Markdown previews: PITHOSAI_SKIP_RESULT_BROWSER, PITHOSAI_RESULT_BROWSER, PITHOSAI_PLAYWRIGHT_CHANNEL.

Interactive session

The default UI is a full-screen TUI: transcript above, input below. Ctrl+S stops the agent; Ctrl+P pauses. Set PITHOSAI_NO_TUI=1 for a classic line prompt (scripts, minimal terminals).

Core slash commands

| Command | Description | |---------|-------------| | /model | List and switch models | | /shell <cmd> | Run a shell command in-process | | /shell cd <dir> | Change working directory (~ supported); syncs session projectPath (1.0.8) | | /list | Show persisted tasks for the current session project (includes projectPath column) | | /list <text> | Filter tasks by title, description, or path | | /select, /show, /show-task, /show-prompt | Work with persisted tasks | | /new | Start a new task id (no prior messages loaded) | | /list-skill, /install-skill, /remove-skill | Same as pithosai skills (ClawHub) | | /grill-me [topic] | Stress-test a plan with one question at a time (1.0.8) | | /exit, /quit | Leave the REPL (1.0.7) |

Tab completion covers slash commands (including /list-project and /grill-me). Directory navigation via /shell cd and ls is tracked for recall (1.0.8).

Virtual projects

Manage multiple workspaces from the REPL without leaving the session. Registry file: ~/.pithosai/projects.json (1.0.8).

| Command | Description | |---------|-------------| | /create-project [name path lang description] | Register a project, create its directory if needed, chdir, and start a new task id. With no arguments, registers the current directory (or shows it if already registered). | | /list-project [filter] | List registered projects (index, name, path). Optional filter matches name, path, language, or description. | | /show-project | Show cwd and registry metadata when cwd matches a saved path | | /switch-project <index> | chdir to a listed project and start a new task id |

/list is scoped to the active session project path and does not collide with /list-project or /list-skill by prefix.

Plan alignment (/grill-me)

/grill-me runs a Matt Pocock–style alignment prompt (one question per turn) to sharpen plans before implementation. Optional text after the command sets the focus topic. Prompt language follows --lang / settings (en, zh, zh-hant, …). A matching Cursor skill lives at .cursor/skills/grill-me/SKILL.md.

Reliability

• Connection-loss retry (1.0.8): Transient API drops (network connection lost) are retried like timeouts.
• Tool result display: Orphaned error tool results are filtered so the transcript stays consistent; ANSI styling in tool output was corrected in 1.0.8.

Startup version check

On launch, the CLI may check npm for a newer @pithosai/pithosai (at most once per 24 hours; state in ~/.pithosai/auto-upgrade-check.json) and run npm install -g @pithosai/pithosai@latest (1.0.7).

Notices use the same resolved CLI language as help. The running process remains the old build until you start pithosai again. When stdin and stdout are TTYs and the full-screen TUI would start, the CLI waits for Enter so upgrade messages are visible.

Disable with PITHOSAI_AUTO_UPGRADE=0 (or false / no / off).

Environment variables

| Variable | Role | |----------|------| | DEEPSEEK_API_KEY, OPENROUTER_API_KEY | API providers | | OPENAI_LOCAL_API_BASE | Local Ollama (/v1 base URL) | | CURSOR_MODEL, CURSOR_AGENT_BIN | Cursor CLI | | PITHOSAI_DB_PATH | SQLite DB (default ~/.pithosai/pithosai.db) | | PITHOSAI_AUTO_UPGRADE | Disable startup check: 0 / false / no / off | | PITHOSAI_SKIP_RESULT_BROWSER | Skip markdown preview (e.g. CI) | | PITHOSAI_RESULT_BROWSER | e.g. chrome for Playwright | | PITHOSAI_TIMEOUT_MS / --timeout | Run limits | | SCRAPERAPI_API_KEY | Some skills / tools |

What's new (v1.0.7 – v1.0.10)

Highlights for the published CLI (excluding unreleased components). Full per-version notes: CHANGELOG.md.

v1.0.10 — Packaging and distribution

• Simplified npm publish layout (.npmignore, narrowed files field).
• Role binaries (rdsai, pmsai, …) ship as POSIX wrappers under scripts/bin-shims/ with corrected paths to pithosai.mjs.
• Dependencies use published @mariozechner/* packages on npm instead of vendored lib/pi-mono copies.

v1.0.9 — Install reliability

• Improved npm install -g resolution for bundled agent dependencies.
• Role commands consolidated as thin shell wrappers invoking pithosai.mjs.

v1.0.8 — Session productivity

• Virtual projects — /create-project, /list-project, /show-project, /switch-project with ~/.pithosai/projects.json.
• /grill-me — Interactive plan alignment (localized prompts).
• /shell cd — In-process directory changes with ~ expansion and directory history.
• Task list — /list shows projectPath, supports /list <text> filter, scopes to the session project.
• Resilience — Automatic retry on connection loss; OpenRouter regression fix; taskRef.projectPath kept in sync after cd and project switches.

v1.0.7 — Models and startup

• DeepSeek V4 — Default deepseek-v4-flash; --pro / --reasoner select deepseek-v4-pro with optional reasoning.
• Startup auto-upgrade — Optional global update check (24 h throttle, TTY-aware prompt).
• REPL exit — /exit and /quit (plain exit goes to the agent).
• Locales — zh-hant resolution fix; render-markdown dist entry fix.

Help

• pithosai --help
• pithosai <command> --help

License

Pithosai is proprietary software; it is not published under an open-source license.

Copyright © 2026 [email protected]. All rights reserved.

See LICENSE in the npm package. The license field in package.json is UNLICENSED (npm convention when no public license is granted).