Skip to main content
from praisonaiagents import Agent

agent = Agent(name="project-agent", instructions="Manage project-scoped agent sessions.")
agent.start("Load my marketing-campaign project session and continue where we left off.")
The user resumes work in the same project folder; prior turns and cumulative usage load automatically. 
cd ~/code/my-app && praisonai run "Build a TODO app"
praisonai run --continue "Add a delete endpoint"

​
Quick Start

1

Start in your project root

cd ~/code/my-app && praisonai run "Build a TODO app"
Project context comes from the git root (or current directory if not in a repo).
2

Continue later

praisonai run --continue "Add a delete endpoint"
Prior user and assistant messages replay before your new prompt — no need to summarise what happened last time.
3

List this project's sessions

praisonai session list
Shows every session --continue could resume for this project — the project’s own sessions plus any globally-stored sessions (from chat, gateway, TUI, API, or a bare Agent(session_id=...)). Duplicates are collapsed; the freshest record wins.

​
How It Works

find_last_session() merges the project-scoped store and the global default store so --continue resolves the most-recent session regardless of how it was created (run, chat, gateway, TUI, API, or a bare Agent(session_id=...)). Sub-agent / forked children are skipped — the last root session wins. It falls back to a child only if the project has none. Each store is scanned with a limit window (default 50).
Where you areProject ID from
Inside a git repogit rev-parse --show-toplevel
Outside a git repoCurrent working directory
Stored hashFirst 8 chars of sha256(absolute_path)
History restore and save wiring landed in PR #1963. If no prior session exists, a warning appears and a new session starts.

​
Persisted usage shape

Every session stores a usage blob in ~/.praisonai/sessions/projects/<project_id>/<session_id>.json. Config-driven consumers and scripts can read this directly.
KeyTypeNotes
input_tokensintCumulative prompt tokens
output_tokensintCumulative completion tokens
cached_tokensintCumulative cached / prefix-hit tokens (when provider reports them)
total_tokensintinput + output (cached not double-counted); mirrored to flat total_tokens on session metadata for back-compat with list_sessions
costfloatUSD, priced via get_pricing(model); mirrored to flat cost
requestsintCount of agent.start() runs that produced usage
The flat total_tokens and cost fields at the session root are mirrors kept for backwards compatibility with any code reading the old schema. SDK helpers (praisonaiagents 1.6.85+): 
from praisonai.cli.state.project_sessions import (
    read_session_usage,
    format_usage_footer,
    accumulate_session_usage,
)

usage = read_session_usage(session_id="abc12345")
print(usage)
# {"input_tokens": 10000, "output_tokens": 2345, "cached_tokens": 0,
#  "total_tokens": 12345, "cost": 0.014, "requests": 3}

footer = format_usage_footer(usage)
print(footer)
# "10,000 in / 2,345 out · $0.0140"

updated = accumulate_session_usage(session_id="abc12345", model="gpt-4o-mini")

​
Configuration Options

FlagDescription
--continueResume the most recent root session for this project — searches both the project store and the global default store
--session <id>Resume a specific session
--fork --session <id>Branch a session to try alternatives
--no-saveOne-off prompt — nothing persisted
session list --allList sessions across all projects

​
Best Practices

Start praisonai run from the repo root so git detection stays consistent — subdirectories still resolve to the same project.
Try alternatives without altering the main thread: praisonai run --fork --session abc123 "try Redis instead".
Quick questions or PII-sensitive input: praisonai run --no-save "How do I hash passwords?".
Review and delete stale sessions across projects periodically.

Run Command

Complete praisonai run with session flags and usage footer

Session Management

Session commands, new table columns, and resume panel

Cost Tracking

Per-session persistence, /cost command, and pricing table