Pithosai (@pithosai/pithosai)

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

What's new in v1.0.7

Models and cost

• Cost-first default: with DEEPSEEK_API_KEY, regular runs use deepseek-v4-flash; --pro uses deepseek-v4-pro; --reasoner uses the pro model with reasoning enabled; --chat explicitly selects flash.
• Interactive /model lists and switches available model keys.
• Aliases: deepSeekPro → deepSeekCoder, deepSeekFlash → deepSeekChat (older keys still work).
• Native DeepSeek chat/coder: requests send thinking: { type: "disabled" } so the provider’s default thinking mode does not force reasoning_content replay on tool-heavy turns (avoids 400 API errors). deepSeekReasoner is unchanged (thinking stays on).

CLI and install

• Optional startup auto-upgrade: checks npm for a newer @pithosai/pithosai (at most once per 24 hours, state in ~/.pithosai/auto-upgrade-check.json), can install @latest globally, uses the same resolved CLI language as help and prompts, and reminds you the current process is still the old build until you run pithosai again. In a TTY when the full-screen agent TUI will start, it waits for Enter so upgrade lines are not lost. Set PITHOSAI_AUTO_UPGRADE=0 (or false / no / off) to disable checks entirely.
• render-markdown: the built dist/render-markdown.mjs entry is fixed so direct execution prints output correctly.

Interactive REPL

• Exit with /exit or /quit only; plain exit / quit are sent to the agent as normal messages.

Earlier in v1.0.5: Encrypted global DB migration, device-bound SQLCipher keys, safer default logging — see CHANGELOG [1.0.5] and the upgrade subsection below.

Install

Node.js ≥ 18.12 required.

npm install -g @pithosai/pithosai

On a global install, the package runs a one-time step: if ~/.pithosai/pithosai.db does not exist, it is created from the bundled schema. Override the path anytime with PITHOSAI_DB_PATH.

What you get

| You run | Purpose | |--------|---------| | pithosai | Main CLI: init, migrate-db, interactive agent, task, heartbeat, skills, memorize, and more. | | rdsai, pmsai, qasai, cosai, mktai, wrsai | Same CLI with a default role (e.g. RD, PM, QA). See Role entrypoints and models below. | | email-monitor | Heartbeat / email-driven task loop (heartbeat bundle). | | render-markdown | Render Markdown files in the terminal. | | init | Manually initialize ~/.pithosai/pithosai.db if needed (usually automatic after global install). |

Choose a model provider

Configure at least one of:

1. DeepSeek — export DEEPSEEK_API_KEY=sk-...

2. OpenRouter — export OPENROUTER_API_KEY=sk-or-...

3. Ollama (local models) — install Ollama on your machine, run a model, and set:

   export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1

   Example local setup:

   ollama run qwen2.5-coder:14b
   export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1

4. Cursor CLI (last resort)

   curl https://cursor.com/install -fsS | bash
   cursor-agent login
   export CURSOR_MODEL=auto

   Use pithosai "your request" --cursor or set CURSOR_MODEL.

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

DeepSeek API (V4)

When using DEEPSEEK_API_KEY (native https://api.deepseek.com), the CLI maps runs to DeepSeek-V4 model ids:

| Your choice | API model id | Typical use | |-------------|----------------|-------------| | Default (e.g. pithosai, rdsai, no --pro / --reasoner) | deepseek-v4-flash | Lower-cost daily coding and regular tasks | | --pro | deepseek-v4-pro | Higher quality coding output for harder tasks | | --chat | deepseek-v4-flash | Explicit chat-style low-cost path | | --reasoner | deepseek-v4-pro with reasoning / thinking enabled | Longer chains-of-thought style replies |

Legacy ids deepseek-chat and deepseek-reasoner are being retired by the provider; see DeepSeek API docs for current parameters (including thinking mode). For extended chain-of-thought on native DeepSeek, use --reasoner / deepSeekReasoner; the default flash/coder paths disable API thinking so agent tool loops stay reliable.

With OPENROUTER_API_KEY only, the same logical paths use OpenRouter slugs deepseek/deepseek-v4-flash (default) and deepseek/deepseek-v4-pro (--pro / --reasoner).

Role entrypoints and models

• rdsai — default role RD, default model path (deepseek-v4-flash unless you pass --pro / --reasoner).
• pmsai, qasai, cosai, mktai — set role PM / QA / CO / MKT and pass --chat, so the chat (flash) model above is used for those binaries without extra flags.
• wrsai — runs the task command with role WR and default language zh (model follows normal task / env resolution for that run).

Quick start

cd your-project
pithosai init
pithosai "Describe what you want done"

• pithosai -i — interactive session with no initial prompt.
• In that interactive loop, type /exit or /quit to leave the CLI (plain exit is treated as a normal message to the agent).
• pithosai --no-interactive "…" — one shot, then exit.
• pithosai -C ./other-dir "…" — use another project directory.
• Every CLI invocation prints a cyan ASCII pithosai slogan banner first.
• On startup, pithosai may check npm for the latest @pithosai/pithosai version (at most once per 24 hours, tracked in ~/.pithosai/auto-upgrade-check.json) and auto-runs npm install -g @pithosai/pithosai@latest when a newer release is found. Upgrade notices use the same resolved CLI language as help and prompts (project settings, --lang, or terminal locale). After an upgrade, this process still runs the old build until you run pithosai again. In a TTY session (same conditions as the full-screen agent TUI), it asks you to press Enter so those lines are not lost when the TUI starts. Set PITHOSAI_AUTO_UPGRADE=0 (or false / no / off) to skip checks entirely.

Prompts load from a local database (default ~/.pithosai/pithosai.db). Optional role overrides live under .pithosai/<role>/ in your project.

Language selection

• Default language is English (en).
• Set language per command with --lang.
• Or export LANG in your shell to set terminal locale preference.

Examples:

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

export LANG=ja_JP.UTF-8
pithosai "今日のタスクを要約してください"

Supported language codes:

• en (English)
• ar (Arabic)
• de (German)
• es (Spanish)
• fr (French)
• it (Italian)
• ja (Japanese)
• ko (Korean)
• nl (Dutch)
• pt (Portuguese)
• zh (Simplified Chinese)
• zh-hant (Traditional Chinese)

Upgrading from v1.0.4 (plaintext pithosai.db)

• Automatic: After upgrading to 1.0.5+, plaintext databases are migrated in place to encrypted storage on first open when encryption support is available.
• Manual (optional): You can run pithosai migrate-db if you want to trigger migration directly.

Run modes (--mode)

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

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

Result previews (terminal or optional Chrome via Playwright) can be tuned with PITHOSAI_SKIP_RESULT_BROWSER, PITHOSAI_RESULT_BROWSER, and PITHOSAI_PLAYWRIGHT_CHANNEL.

Common commands

| Command | What it does | |---------|----------------| | pithosai init [dir] | Scaffold project, .pithosai/sessions/, settings. | | pithosai migrate-db | Convert a legacy plaintext global DB to SQLCipher (optional; usually automatic on first open). | | pithosai add-role <role> | Add a role to the project. | | pithosai task --file <md> | Watch a task file and run tasks sequentially. | | pithosai memorize --start … --end … -r <role> | Build .pithosai/<role>/memory.md from stored tasks. | | pithosai heartbeat / heartbeat --once | Email-driven task pipeline (needs 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 (--timeout, --lang, --role, --log-path, etc.).

Interactive session (short)

In a normal terminal, the default UI uses a full-screen TUI (bottom input, scrolling transcript). Ctrl+S stops a run; Ctrl+P pauses. Slash commands include /model, /shell, /list, /show-task, /show-prompt, and skill helpers. Set PITHOSAI_NO_TUI=1 for a classic line-based prompt (e.g. scripts or minimal terminals).

Environment variables

| Variable | Role | |----------|------| | CURSOR_MODEL, CURSOR_AGENT_BIN | Cursor CLI integration | | DEEPSEEK_API_KEY, OPENROUTER_API_KEY | API providers | | OPENAI_LOCAL_API_BASE | Local Ollama endpoint (requires local Ollama install) | | PITHOSAI_DB_PATH | SQLite DB path (default ~/.pithosai/pithosai.db) | | PITHOSAI_AUTO_UPGRADE | Set to 0 / false / no / off to disable startup version check and global auto-install | | PITHOSAI_SKIP_RESULT_BROWSER | Skip markdown preview (e.g. CI) | | PITHOSAI_RESULT_BROWSER | chrome for Playwright browser preview | | PITHOSAI_TIMEOUT_MS / --timeout | Run time limits | | SCRAPERAPI_API_KEY | Used by skills / some tools |

Help and support

Use pithosai --help for top-level options, and pithosai <command> --help for command-specific details.

License

Pithosai is proprietary software — it is not published under an open-source or ISC license.

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

See LICENSE for the copyright notice (included in the npm package). The license field in package.json is UNLICENSED, which npm uses when no public license is granted.