praisonai-code
Agentic terminal CLI for PraisonAI — the terminal-native agent product
(run, chat, code, warm runtime, CLI backends) extracted from the
praisonai wrapper.
Analogues: opencode, codex, gemini-cli.
Status
C0–C5 complete. C6 integration gate verified — see
src/praisonai/tests/C6_VERIFICATION.md.
| Step | Scope | Status |
|---|---|---|
| C0 | Scaffold | Done |
| C1 | runtime/ + cli_backends/ |
Done |
| C2 | interactive/, execution/, ui/, output/, state/ |
Done |
| C3 | Agentic commands | Done |
| C4 | Agentic features | Done |
| C5 | main.py, app.py, config/session/utils + shims |
Done |
| C6 | Integration gate + sign-off | Done |
| C7 | Hot-path standalone (agentic CLI without wrapper import) | Done |
praisonai_code.runtime— warm local runtime (daemon + thin client).praisonai_code.cli_backends— CLI backend implementations (e.g. Claude Code).praisonai_code.llm— endpoint resolution, credentials, model catalogue.praisonai_code.tool_resolver— YAML tool name resolution.
See src/praisonai/tests/C7_VERIFICATION.md for the hot-path sign-off checklist.
Dependency rules
praisonai (main) → depends on praisonai-code
praisonai-code → depends on praisonaiagents (core SDK)
praisonai-code also pulls in its own third-party runtime deps (rich, typer,
click, textual, PyYAML, python-dotenv, litellm, mcp, pydantic — see
pyproject.toml). The rules above govern the inter-package direction.
C7 (hot path complete): Standalone
pip install praisonai-codesupports core agentic terminal commands without importing the wrapper on the hot path. Approval backends resolve locally viapraisonai_code.cli.features._approval_bridge(channel bots delegate to the wrapper). Optional features (observability sinks, framework adapters, bots/gateway) remain wrapper-only viapraisonai_code._wrapper_bridge.
Standalone limits (pip install praisonai-code only)
The terminal-native commands (run, chat, code, doctor, daemon) live in
praisonai_code.cli.commands.* and resolve via LazyCommandGroup without
importing the wrapper. Only commands in _WRAPPER_RESIDENT_COMMANDS (see
praisonai_code/cli/app.py) require pip install praisonai.
| Command | Works standalone? | Notes |
|---|---|---|
praisonai-code --version |
Yes | |
run --help, config, doctor |
Yes | |
run --output actions "…" |
Yes | In-process Agent (structured events). run modes: silent (default), plain, actions, verbose, json, stream, stream-json |
run --output json/stream/stream-json "…" |
Yes | In-process Agent. json prints one single-line {result, status} envelope on stdout for every outcome (ok, failed, blocked, truncated); stream prints the answer; stream-json activates NDJSON events on stdout |
run "…" (default) |
Yes | Standalone renders in-process (human-readable text, exit-code contract as --output actions); delegates to the wrapper's handle_direct_prompt when it is installed. --image still needs praisonai |
run --output plain/verbose/silent "…" |
Yes | Same in-process text render when standalone; wrapper delegation when installed |
chat --output plain "…" |
Yes | One-shot; interactive REPL also in code package. chat modes: actions (default), plain, verbose, json, silent |
code --help |
Yes | Full code assistant command registered |
daemon start (foreground) |
Yes | |
daemon start --background |
Yes | Spawns python -m praisonai_code.runtime |
batch, docs, langfuse, flow, n8n, train, … |
No | _WRAPPER_RESIDENT_COMMANDS — needs pip install praisonai |
bot, gateway, pairing, … |
No | Needs praisonai bot package |
Known limitations:
praisonai-code --helpmay crash on Windows (cp1252) due to emoji in command descriptions — tracked separately.- Piped stdin (
file | run) is not yet supported on Windows.
For bots, gateway, batch, observability sinks, and the wrapper-resident commands
above, install the full wrapper: pip install praisonai.
Completed C7 steps:
praisonai_code._registry— vendored plugin registry (no wrapper import)praisonai_code._version/runtime/descriptor.py— version frompraisonai-codepraisonai_code.__main__+praisonai-codeconsole script — standalone entrypraisonai_code._logging— CLI logging without wrapper dependencypraisonai_code.llm.*— env, credentials, catalogue, configpraisonai_code._framework_availability,_safe_loader,tool_resolver— execution helpers- Namespace cleanup —
praisonai_code.cli.features.*local imports on agentic path
Backward compatibility is preserved via PEP 562 shims at the old
praisonai.* import paths, so pip install praisonai and
from praisonai.cli.main import PraisonAI keep working unchanged.
Install
Recommended (includes wrapper + bots/gateway):
pip install praisonai
Standalone code package (agentic CLI only):
pip install praisonai-code
praisonai-code --version
python -m praisonai_code --help
Development / monorepo:
pip install -e src/praisonai-agents
pip install -e src/praisonai-code
pip install -e src/praisonai
python -c "import praisonai_code; print(praisonai_code.__version__)"
PyPI: Published as praisonai-code after praisonaiagents in the
three-package release order (see pypi-release.yml).
Shell execution (PRAISON_SHELL)
execute_command runs argv directly (shell=False) as a prompt-injection
defence. Shell operators — &&, ||, |, >, >>, ;, `, $( — are
therefore not interpreted, and a command containing one is refused rather
than run with the operator silently dropped. (Dropping it and returning exit 0
gives the model nothing to correct on; a redirect that creates no file must not
report success.)
PRAISON_SHELL |
Behaviour |
|---|---|
unset / off (default) |
Shell syntax is refused with an explanation. Plain commands run as before. |
sandboxed |
A real /bin/sh -c runs inside OS-native containment — Seatbelt (sandbox-exec) on macOS, bubblewrap on Linux — restricted to the workspace plus the temp dir, network denied. |
unsafe |
A real /bin/sh -c with no containment. Opt-in only; never used as a fallback. |
sandboxed mode measures enforcement before trusting it: it runs a probe
child that tries to write outside the writable set, and refuses to run at all
if that write succeeds. It never degrades quietly to an uncontained shell.
Approval is unchanged — the real-shell path is gated by the same
require_approval(risk_level="critical") guard, under the same
execute_command tool identity.
Session commands
| Command | Does |
|---|---|
/compact [strategy] |
Compact the conversation context (frees tokens). Runs automatically at a turn boundary when the session nears the model's budget. |
/compact-display (/dense) |
Toggle compact output rendering — the old meaning of /compact. |
/map [path] |
Ranked repository map (tree-sitter symbol extraction). |
/git-status, /git-diff, /git-log [n], /git-commit [msg], /git-undo |
Git from inside the session. /git-commit generates a message from the staged diff when none is given. |
MCP servers declared under mcp.servers in project config are loaded into the
code session's tool set. Disable with PRAISON_TOOLS_DISABLE=mcp.
Trust gate. Project-declared local (stdio) MCP servers spawn a
subprocess on the host, so a cloned repository could run a repo-controlled
script the moment the session opens. They are therefore not started
automatically: set PRAISONAI_MCP_TRUST=1 to allow the current workspace to
start its local MCP subprocesses. Remote (URL) servers spawn no local process
and are unaffected. Config is resolved from the selected --workspace, not the
process working directory.
1 maintainer
Metadata
1 maintainer
Release files for praisonai-code 0.1.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| praisonai_code-0.1.12.tar.gz | 974.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| praisonai_code-0.1.12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.1 MB
Release files / praisonai_code-0.1.12.tar.gz
| Download URL | praisonai_code-0.1.12.tar.gz |
|---|---|
| Size | 974.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eea860da63a21d0c4945490d76d7af96445fe6987952722aaa653606a4a88b6e
|
|
BLAKE2b-256 checksum How to use checksums |
b34ff3f5a24a4e85a6f9344b8be66fefa5fe02c576f6018bca3cefe5dc6d835a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / praisonai_code-0.1.12-py3-none-any.whl
| Download URL | praisonai_code-0.1.12-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
849c12d8fd8d60aaade83eb4811cdc4739f87175c4e917f09fd14e5e650f2333
|
|
BLAKE2b-256 checksum How to use checksums |
a4901b9f571641b4d94b5014d37963757a3a90e6a0f3a85423cac1648b2376e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
