Code

Code assistant mode for programming tasks

The code command starts a code assistant session optimized for programming tasks.

Usage

praisonai code [OPTIONS] [PROMPT]

Arguments

Options

Append to the system prompt

--append-system-prompt adds a one-off suffix to the assembled system prompt for a single invocation. It is never persisted and disappears when the process exits.

# Literal text
praisonai code --append-system-prompt "Always answer in French"

# Read the suffix from a file (@file form)
praisonai code --append-system-prompt @policy.md

Omit the flag and set the environment variable instead — handy for CI:

export PRAISONAI_APPEND_SYSTEM_PROMPT="Reply in strict JSON, no prose."
praisonai code

See Append System Prompt for the full behaviour.

Piped Input

praisonai code reads piped stdin when the prompt is provided in the shell pipeline.

cat data.json | praisonai code "Write a parser for this shape"

Prompt argument is merged first, piped body second (joined with \n). See Piped Input.

Step budget for coding sessions

praisonai code runs with a coding-sized step budget by default: 200 steps, applied to both tool-execution loops.

The core Agent defaults (max_steps=20, max_tool_calls_per_turn=10) are tuned for a general-purpose Q&A agent with two or three tools, and are left untouched — no library user’s behaviour changes. But 10 tool calls is “list files, read two files, one grep”: it cannot reach a test run. The coding CLI raises the ceiling for its own sessions only.

Override

1. Explicit flag

   praisonai code --max-steps 300 "Refactor the auth module across all files"

2. Environment fallback (CI / sandbox)

   export PRAISONAI_CODE_MAX_STEPS=300
   praisonai code "Refactor the auth module across all files"

Precedence: --max-steps flag > PRAISONAI_CODE_MAX_STEPS env > DEFAULT_CODE_MAX_STEPS (200). An unparseable or non-positive value falls through to the next source.

The flag raises both budget knobs to the same value, because:

Raising only one leaves the other as the real (and invisible) ceiling.

See Step Budget for the general ExecutionConfig.max_steps contract and how to detect truncation with agent.last_stop_reason.

Headless truncation contract (code -p)

A budget-exhausted headless run exits 2 with status: "truncated" — distinct from a hard failure (1) and a clean completion (0).

This matches praisonai run → truncation and closes a hazard where a wrap-up summary (a perfectly non-empty string) was classified as status: "ok", exit 0, silently reporting truncation as success to CI and benchmark adapters.

praisonai code -p --output json --max-steps 6 \
  "Run pytest and fix every failing test until 0 failures"

# → exit 2
# → {"result": "Tool call limit reached (…). Task may be too complex …",
#    "session_id": null, "usage": {…}, "status": "truncated"}

Under --output text, a stderr warning follows the printed result:

Warning: run hit the step/tool-call budget; the output above is a summary of partial progress, not a completed task. Re-run with a higher --max-steps.

JSON / stream-JSON consumers do not see this stderr line — the status: "truncated" field is the machine signal.

The shared truncation check (run._run_was_truncated) resolves through agent.last_stop_reason == "max_steps", so code -p and praisonai run agree on the 0 / 1 / 2 exit-code contract.

First-run credential gate

praisonai code routes first-run onboarding through the shared credential gate, so a keyless newcomer is offered the setup wizard (interactive) or exits with a hint (headless) instead of dead-ending on a raw provider error.

See First-run Onboarding for the full flow and Setup for the wizard.

Headless / scripting mode

-p/--print runs one task and prints a clean, machine-readable result — no Chat mode: banners, no profiling block — then exits with a code that reflects success or failure. This is the scripting parity code shares with run --output json and chat --json.

praisonai code -p "Write a Python function to sort a list" --output json

JSON envelope

--output json (the default under -p) prints a single-line JSON object on stdout:

{"result": "def sort_list(items): return sorted(items)", "session_id": null, "usage": {"in": 128, "out": 42, "cost": 0.0001}, "status": "ok"}

On a model with no known price, cost is null instead of a guessed figure:

{"result": "def sort_list(items): return sorted(items)", "session_id": null, "usage": {"in": 128, "out": 42, "cost": null}, "status": "ok"}

Text mode

--output text prints just the result on stdout — nothing else — so it pipes cleanly:

praisonai code -p "What is 2+2?" --output text
# 4

Errors go to stderr; status is carried by the exit code.

Exit-code contract

The exit code lets CI, benchmarks, and shell scripts branch on success without parsing stdout.

See Headless truncation contract (code -p) for the truncated case.

if praisonai code -p "Generate the release notes" --output text > notes.md; then
  echo "wrote notes.md"
else
  echo "generation failed" >&2
fi

Scripted multi-turn with --resume

--resume <id> composes with -p so a script can carry a session across calls. The id flows back out in the envelope’s session_id:

praisonai code --resume my-feature -p "Draft the auth refactor" --output json
praisonai code --resume my-feature -p "Now add tests"          --output json

Fail-closed options

Headless mode runs a minimal code agent, so options that need the full interactive wiring are rejected up front (exit 1) rather than silently dropped:

Two more guards keep the contract explicit: --output without -p errors, and -p without a prompt errors.

The mcp tool group is enabled by default under -p as of PR #4965 — if your project declares mcp.servers, those tools reach the headless agent alongside the built-ins. Opt out with PRAISON_TOOLS_DISABLE=mcp (the same knob that works interactively). See MCP tools in coding sessions.

Honored under -p: --model, --thinking, --verbose, --workspace, --resume / --session / --continue, --tools, --agent, and --plan (as of PraisonAI PR #4026). --tools and the profile’s named tools are merged onto the default headless coding toolset (de-duped by identity), so custom tools add to the defaults rather than replacing them. --plan and a profile’s declarative permissions are enforced via a non-interactive approval backend, so honouring the scope is a tightening (deny/ask fails closed) — never an interactive prompt that would stall a scripted run.

Sessions

praisonai code shares the canonical session store at ~/.praisonai/sessions/ (Windows: %USERPROFILE%\.praisonai\sessions\). Every conversation you start here is the same session object the rest of the CLI reads and writes.

Sessions created inside praisonai code are visible to:

• praisonai session list (and list --all)
• praisonai session show <id> / delete <id> / export <id> / share <id> / unshare <id>
• praisonai run --continue / --session <id> — same id, same conversation
• the praisonai dashboard

# Start a session in code, then continue it from run
praisonai code --session my-feature "Draft the auth refactor"
praisonai run --session my-feature "Now add tests"

# List and export the same session
praisonai session list
praisonai session export my-feature

See Session Management for the full command set and Storage Paths for where files live.

Examples

Start code assistant

praisonai code

Ask a coding question

praisonai code "Write a Python function to sort a list"

Specify language context

praisonai code --language python "Explain decorators"

Disable safe mode (opt out of approval prompts)

praisonai code --no-safe "Refactor main.py"

Full bypass (no approval prompts, applies to subprocess tree)

praisonai code --dangerously-skip-approval "Clean up old logs"

Headless one-shot for scripts

# Machine-readable JSON envelope on stdout, status-reflecting exit code
praisonai code -p "Write a Python function to sort a list" --output json

See Headless / scripting mode for the envelope shape and exit-code contract.

Headless one-shot with a custom tool

--tools is now first-class under -p. The resolved tools are merged onto the default headless coding toolset (ACP + edit + search + LSP + MCP), so custom tools add to the defaults rather than replacing them.

# Add the `github` tool to a scripted coding run
praisonai code -p --tools github "Open a PR that fixes the failing lint" --output json

With mcp.servers set in your project config, MCP tools are in the default set too — the resolved --tools argument stacks on top of ACP + edit + search + LSP + MCP. See MCP tools in coding sessions.

--tools accepts either comma-separated names resolved through ToolResolver (identical to run --tools) or a ./tools.py file path. If a user tools.py fails at import time, the failure is reported through the same machine-readable JSON envelope (status: "error", non-zero exit) — never as a raw traceback.

Headless one-shot under a named agent profile

--agent <name> loads a profile from .praisonai/agents/ and applies its instructions, role, goal, llm, and named tools to the headless run. Its declarative permissions are enforced via a non-interactive approval backend, so a pinned least-privilege profile runs safely in CI.

# Least-privilege review profile — instructions + permission scope from .praisonai/agents/reviewer.md
praisonai code -p --agent reviewer "Audit src/security/ for auth bugs" --output json

An explicit --model still wins over the profile’s llm. See Custom Agents & Commands for profile definitions.

Headless read-only planning (--plan)

--plan under -p runs a read-only headless session: reads, searches, and LSP queries are allowed, but every mutating tool (write, edit, shell) is denied by a non-interactive PermissionMode.PLAN backend. Ideal for CI review jobs that must produce a plan without touching the tree.

# Plan-only headless run — writes/edits/shell are denied
praisonai code -p --plan "Draft a migration plan for the auth module" --output json

--plan overrides any profile permission scope with the read-only planning mode. See Permission Modes and Approval.

Read-only planning session

# REPL session that can read/search but never writes or shells
praisonai code --plan "Draft a migration plan for the auth module"

--plan is the read-only planning permission mode (PermissionMode.PLAN). See Permission Modes and Permissions.

Reasoning effort (per invocation)

praisonai code --thinking high "Refactor src/utils.py for readability"

Custom agent profile

# Profile defined in .praisonai/agents/plan.md
praisonai code --agent plan "Review the auth module and propose a refactor"

# Profile + reasoning effort combined
praisonai code --agent reviewer --thinking high "Audit src/security/"

See Custom Agents & Commands for profile definitions and Thinking for budget levels.

Append a one-off instruction (per invocation)

praisonai code --append-system-prompt "Always answer in French"

The text is appended to the end of the system prompt for this run only — never written to any agent file. See Append System Prompt.

Project context

By default, praisonai code walks up from the current directory to your git root and prepends any AGENTS.md / CLAUDE.md / agents.md / .agents/AGENTS.md it finds to the agent’s system prompt, layered on top of ~/.praisonai/AGENTS.md. Pass --no-context (or set PRAISON_NO_CONTEXT=true) to disable. See Context Files for details.

Workspace directory

praisonai code runs its file, edit, search, and shell tools inside one workspace directory. Everything the agent reads and writes is contained there.

Pick a workspace explicitly

praisonai code --workspace ./src "Refactor the auth module"

Everything the agent reads or writes stays inside ./src.

Pick a workspace with an environment variable

export PRAISONAI_WORKSPACE=/path/to/project
praisonai code "Add tests for user.py"

PRAISONAI_WORKSPACE is the canonical name. The older PRAISON_WORKSPACE still works for backwards compatibility, but PRAISONAI_WORKSPACE wins when both are set.

Resume back into the same directory

praisonai code --continue           # resumes the last session in its original directory
praisonai code --session abc123     # resumes that specific session in its original directory

Launch praisonai code --continue from any shell — the tools re-root into the directory the session was created in, so the conversation stays consistent.

If the recorded directory no longer exists you’ll see a warning and the tools fall back to the current directory:

⚠ Session workspace no longer exists: /old/path — using current directory instead.

An explicit --workspace always wins over the resumed directory.

Windows Automation

For Windows automation scenarios, use the --no-acp flag and set UTF-8 encoding. The -w flag is now honored end-to-end, so the agent’s tools operate inside the directory you pass:

# Windows PowerShell
$env:PRAISON_APPROVAL_MODE = "auto"
$env:PYTHONIOENCODING       = "utf-8"

praisonai code -w . --no-acp "Fix the failing tests"

See the Windows Automation section in Real-world Examples for complete setup instructions.

Auto checkpointing & in-session undo

Workspace checkpointing is on by default for interactive praisonai code sessions, so /undo and /revert work out of the box. Disable per-run with --no-checkpoints, or project-wide with checkpoints.auto: false (or PRAISONAI_CHECKPOINTS=off).

praisonai code "Refactor auth module"

How /undo differs by mode

Interactive slash commands

Type these inside a praisonai code REPL (checkpointing is on by default; disable with --no-checkpoints):

Both commands show a diff preview before restoring and refuse to run while a turn is still in progress.

One-shot revert from CLI

praisonai code --revert last

Shows the diff preview and restores the workspace, then exits.

Project config

Enable checkpointing for all praisonai code sessions in a project:

# agents.yaml
checkpoints:
  auto: true
  storage_dir: ./.praisonai/checkpoints   # optional — shared with praisonai run

Precedence (highest last): default → checkpoints.auto (config) → PRAISONAI_CHECKPOINTS (env). Interactive praisonai code passes default=True, so checkpointing is on unless you disable it.

See Checkpoints for the full checkpoint feature reference.

Shell execution (PRAISON_SHELL)

PRAISON_SHELL picks the containment posture for every execute_command call.

The real-shell path is gated by the same critical-risk execute_command approval as the plain executor. See Shell Modes and OS Sandbox.

MCP tools in coding sessions

Declaring mcp.servers in your project config makes those tools appear inside praisonai code (both the interactive TUI and the -p headless one-shot) as a standard mcp tool group.

# praison.yaml
mcp:
  servers:
    tiny_add:
      command: python
      args: ["tiny_add_server.py"]

praisonai code

The coding session reuses the same collector as praisonai run, so the server’s tools (for example tiny_add) reach the agent. Two rules apply:

• Opt out with PRAISON_TOOLS_DISABLE=mcp to drop the whole group.
• No shadowing — an MCP server can never override a built-in tool name; the built-in wins and the duplicate MCP tool is skipped.

See MCP and Load MCP Tools.

See Also

• Chat – General chat mode (--json headless output)
• Piped Input – Compose code -p in Unix pipelines and CI
• LSP Code Intelligence – Language server integration
• Approval – Tool approval and safety defaults
• Checkpoints – Workspace checkpointing and undo
• Step Budget – The max_steps contract and the coding-sized default