pico-cli 0.1.0__tar.gz

pico_cli-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

pico_cli-0.1.0/.scratch/headless-agent/issues/01-unified-ai-call.md

@@ -0,0 +1,13 @@
+# 01 — Unified AI call + OpenRouter client
+
+**What to build:** a streaming, async, provider-agnostic "AI call" in `pico_ai`. Given a prompt (and optional tool definitions), it sends a request to OpenRouter and returns a normalized stream of text / thinking / tool-call blocks plus usage. The API key comes from the environment; the model is configurable with a default.
+
+**Blocked by:** None — can start immediately.
+
+**Status:** ready-for-agent
+
+- [ ] A unified request/response type exists that is provider-agnostic (no OpenRouter-specific fields leak into callers).
+- [ ] An async, streaming client sends a prompt to OpenRouter and yields normalized blocks (text, thinking, tool-call) as they arrive.
+- [ ] The response includes usage (input/output tokens) when the provider reports it.
+- [ ] Tool definitions round-trip: a caller can pass tool schemas and receive tool-call blocks with name + arguments.
+- [ ] A fake transport lets tests exercise the client with no network.

pico_cli-0.1.0/.scratch/headless-agent/issues/02-tracer-bullet-headless-text-response.md

@@ -0,0 +1,12 @@
+# 02 — Tracer bullet: headless text response
+
+**What to build:** `pico run "…"` returns a text response and persists an append-only session (user node + assistant node) to disk, driven by a minimal FSM (`idle → streaming → done`). No tools yet.
+
+**Blocked by:** 01 — Unified AI call + OpenRouter client.
+
+**Status:** ready-for-agent
+
+- [ ] `pico run "hello"` prints the model's text response.
+- [ ] A session is persisted as JSONL with a user node and an assistant node, each with id/parent_id/timestamp/payload.
+- [ ] The FSM transitions idle → streaming → done for a simple prompt.
+- [ ] A scripted fake provider drives the loop deterministically in tests (no network).

pico_cli-0.1.0/.scratch/headless-agent/issues/03-tools.md

@@ -0,0 +1,14 @@
+# 03 — Tools: read / write / edit / bash
+
+**What to build:** the agent can invoke the four tools, feed results back, and loop `streaming ⇄ tool_executing` until done. Bash echoes commands and requires an opt-in flag.
+
+**Blocked by:** 02 — Tracer bullet: headless text response.
+
+**Status:** ready-for-agent
+
+- [ ] The agent can read a file, write (create/overwrite) a file, and edit a file with a surgical search/replace patch.
+- [ ] The agent can run a bash command and receive its output and exit code.
+- [ ] Tool results are fed back into the conversation so the model can act on them.
+- [ ] The loop continues streaming ⇄ tool_executing until the model stops requesting tools.
+- [ ] Bash commands are echoed before execution, and bash is disabled unless an opt-in flag is set.
+- [ ] Tool errors (non-zero exit, missing file) surface as tool results rather than crashing.

pico_cli-0.1.0/.scratch/headless-agent/issues/04-session-fork.md

@@ -0,0 +1,11 @@
+# 04 — Session fork & branch-scoped context
+
+**What to build:** rewind to an earlier node and fork a new branch; only the active branch is sent to the model.
+
+**Blocked by:** 02 — Tracer bullet: headless text response.
+
+**Status:** ready-for-agent
+
+- [ ] A session can fork from an earlier node, creating a new branch.
+- [ ] Only the active branch's nodes are assembled into the model context; abandoned branches are excluded.
+- [ ] Forking is append-only: existing nodes are never edited or deleted.

pico_cli-0.1.0/.scratch/headless-agent/issues/05-compaction.md

@@ -0,0 +1,11 @@
+# 05 — Compaction (auto + manual)
+
+**What to build:** auto-compaction at the token threshold (`contextTokens > window − reserve`) and manual `/compact [instructions]`, summarising old turns into a compaction-summary node.
+
+**Blocked by:** 02 — Tracer bullet: headless text response.
+
+**Status:** ready-for-agent
+
+- [ ] Auto-compaction fires when context tokens exceed window − reserve (reserve default 16384).
+- [ ] Compaction summarises old turns into a compaction-summary node and keeps the system prompt + recent window.
+- [ ] Manual `/compact [instructions]` triggers compaction with steering instructions.

pico_cli-0.1.0/.scratch/headless-agent/issues/06-extension-binding.md

@@ -0,0 +1,16 @@
+# 06 — Extension binding & plugin loading
+
+> **Superseded by ADR-0003 (2026-09-30):** the generic plugin binding below was
+> deliberately removed. The core is hardcoded; curated extensions only (fixed
+> observe-only hooks + `SKILL.md` skills). Kept for history — do not implement.
+
+**What to build:** `register_tool`, `register_provider`, and lifecycle hooks (`on_session_start`, `tool.before.*`, `tool.after.*`); plugins load from a directory and via explicit registration.
+
+**Blocked by:** 03 — Tools: read / write / edit / bash.
+
+**Status:** ready-for-agent
+
+- [ ] A plugin can register a custom tool that the agent can invoke.
+- [ ] A plugin can register a custom provider.
+- [ ] Lifecycle hooks fire: on_session_start, tool.before.*, tool.after.*.
+- [ ] Plugins load from a plugins directory and via explicit registration.

pico_cli-0.1.0/.scratch/headless-agent/issues/07-config-file.md

@@ -0,0 +1,11 @@
+# 07 — Config file (settings.json)
+
+**What to build:** `~/.pico/settings.json` supplies model, reserve tokens, and session location; sensible defaults when absent.
+
+**Blocked by:** 02 — Tracer bullet: headless text response.
+
+**Status:** ready-for-agent
+
+- [ ] Settings load from ~/.pico/settings.json when present.
+- [ ] Model, reserve tokens, and session location are configurable.
+- [ ] Sensible defaults apply when the file is absent or a key is missing.

pico_cli-0.1.0/.scratch/headless-agent/spec.md

@@ -0,0 +1,112 @@
+---
+title: Headless agent runtime
+labels:
+  - ready-for-agent
+---
+
+# Headless Agent Runtime
+
+## Problem Statement
+
+The user wants a Python CLI coding agent — inspired by Pi's modular, plugin-driven architecture — that can autonomously (yolo mode) perform coding tasks in a repository: reading, writing, and editing files, and running bash commands, while keeping a resumable, branchable session history and automatically compacting context to stay within the model's token budget.
+
+Today the codebase is only a scaffold: four empty packages (`pico_ai`, `pico_core`, `pico_sdk`, `pico_tui`) with no agent loop, no LLM integration, no session persistence, and no tools. There is nothing runnable yet.
+
+## Solution
+
+Build the **headless agent runtime** across three packages, so that `pico run "…"` works end-to-end without a UI:
+
+- **`pico_ai`** — a unified "AI call" type that normalises every provider behind a single request/response shape, with a streaming, async OpenRouter client as the first (and only) gateway.
+- **`pico_core`** — an explicit finite-state-machine agent loop that maintains an append-only session tree and auto-compacts context.
+- **`pico_sdk`** — a headless `AgentSession` API plus the extension/plugin binding, exposed through a `pico run "…"` command.
+
+The TUI (`pico_tui`) is a later milestone.
+
+## User Stories
+
+1. As a developer, I want to run pico headlessly with a single prompt (`pico run "…"`), so that I can automate a coding task without an interactive UI.
+2. As a developer, I want pico to read files in my repo, so that the agent can understand the codebase before acting.
+3. As a developer, I want pico to write (create or overwrite) files, so that it can produce new code.
+4. As a developer, I want pico to edit files surgically with search/replace patches, so that it can make targeted changes without rewriting whole files.
+5. As a developer, I want pico to run bash commands, so that it can build, test, and inspect the repo.
+6. As a developer, I want pico to operate in yolo mode with no per-step approval, so that it can complete multi-step tasks autonomously.
+7. As a developer, I want to see each bash command echoed before it runs, so that I can audit what the agent is doing.
+8. As a developer, I want an opt-in flag that permits unsandboxed bash execution, so that I explicitly consent to the risk.
+9. As a developer, I want pico to loop between streaming and tool execution until the task is done, so that it can self-correct (e.g. run tests, then fix failures).
+10. As a developer, I want tool results fed back into the conversation, so that the agent can act on command output and file contents.
+11. As a developer, I want pico to handle tool errors (non-zero exit, missing file) gracefully, so that it can recover or report rather than crash.
+12. As a developer, I want to reach multiple LLM providers through one gateway, so that I can switch models without code changes.
+13. As a developer, I want streaming responses, so that I can watch output as it is generated.
+14. As a developer, I want thinking (reasoning) blocks preserved in the transcript, so that I can review the agent's reasoning.
+15. As a developer, I want assistant responses to carry usage/token counts, so that I can track cost.
+16. As a developer, I want my session persisted as an append-only tree of nodes, so that I can resume and review it later.
+17. As a developer, I want to fork from an earlier node, so that I can rewind after a broken change without starting over.
+18. As a developer, I want only the active branch sent to the model, so that abandoned branches do not waste tokens.
+19. As a developer, I want automatic context compaction, so that long sessions stay within the model's context window.
+20. As a developer, I want to manually trigger compaction with steering instructions, so that I can control what gets summarised.
+21. As a developer, I want reserve tokens held back for the model's response, so that compaction leaves room for output.
+22. As a developer, I want a config file for settings, so that I can tune the agent without editing code.
+23. As a developer, I want sessions stored per-session in a known location, so that I can find and inspect them.
+24. As a developer, I want an explicit, observable state machine, so that I can reason about and test the agent's behaviour.
+25. As a developer, I want failures surfaced as a clear error state, so that I can diagnose what went wrong.
+26. As a developer, I want a headless library API (`AgentSession`), so that I can embed pico in my own scripts and tools.
+27. As a developer, I want to feed input and harvest output streams programmatically, so that I can build automation on top of pico.
+28. As a plugin author, I want to register custom tools, so that I can extend the agent's capabilities.
+29. As a plugin author, I want to register custom providers, so that I can add LLM backends beyond the gateway.
+30. As a plugin author, I want lifecycle hooks (session start, before/after tool), so that I can intercept and react to agent events.
+31. As a plugin author, I want plugins loaded from a plugins directory and via explicit registration, so that I can choose how to distribute them.
+32. As a developer, I want the unified "AI call" shape used for every provider, so that provider-specific details are normalised away.
+
+## Implementation Decisions
+
+- **Monorepo split (ADR-0001).** Four packages with a one-way dependency chain `pico_ai ← pico_core ← pico_sdk ← pico_tui`. This spec covers the first three; `pico_tui` is out of scope.
+- **Tree-based append-only session (ADR-0002).** A session is a tree of immutable nodes; nodes are never edited or deleted, only built upon. Branches are root-to-leaf timelines; forking rewinds to an earlier node and starts a new branch. Only the active branch is sent to the model.
+- **Unified "AI call".** A single provider-agnostic request/response shape. OpenRouter is the single gateway (one HTTP client, one key, all models). Native adapters are deferred to plugins.
+- **Streaming + async.** The core is `asyncio`-based; responses stream token-by-token.
+- **Explicit FSM.** The agent loop is a finite state machine. States (from the design):
+
+  ```
+  idle → streaming ⇄ tool_executing → done
+           ↓
+        compacting          (triggered by token threshold)
+  error                    (reachable from any state)
+  ```
+
+  Yolo mode means there is no approval/confirmation state.
+- **Node payload vocabulary.** Each node's payload is one of: user, assistant (block-granular: text / thinking / tool-call), tool request, tool result, compaction summary. Node shape (from the design):
+
+  ```
+  Node { id, parent_id, timestamp, payload }
+  payload: User | Assistant | ToolRequest | ToolResult | CompactionSummary
+  ```
+
+- **Four core tools.** `read` (file), `write` (create/overwrite), `edit` (surgical search/replace patch), `bash` (shell). Bash runs unsandboxed with a visible command echo and an opt-in flag.
+- **Compaction.** Auto-triggered when `contextTokens > contextWindow − reserveTokens` (reserve default 16384), plus a manual `/compact [instructions]` override. Compaction summarises older turns into a compaction-summary node, keeping the system prompt and a recent window.
+- **Config & sessions.** Settings in `~/.pico/settings.json`; sessions persisted as `.jsonl` under `~/.pico/sessions/<id>.jsonl`.
+- **Extension binding.** `register_tool`, `register_provider`, and lifecycle hooks (`on_session_start`, `tool.before.*`, `tool.after.*`). Plugins load from a plugins directory and via explicit registration.
+  > **Superseded by ADR-0003 (2026-09-30):** the generic binding was removed in favour of a hardcoded core with curated extensions (fixed observe-only hooks + `SKILL.md` skills). See `docs/adr/0003-hardcoded-core.md`.
+- **Models in pydantic v2.**
+- **Deferred as plugins.** MCP, sub-agents, plan mode, and local to-do tracking are explicitly out of the core and will be added later as plugins.
+
+## Testing Decisions
+
+- **What makes a good test.** Assert on external behaviour — the observable session tree, the tool calls made, and the FSM outcome — not on internal implementation. Drive everything through the public `AgentSession` API.
+- **Primary seam — the provider boundary.** Inject a scripted fake "AI call" (predetermined responses and tool requests), and the whole loop becomes deterministic and network-free. This is the single high seam.
+- **Supporting seam — the filesystem boundary.** The four tools are tested against a temporary working directory, since they touch the disk.
+- **Modules under test.** `pico_ai` (provider normalisation, streaming parsing), `pico_core` (FSM transitions, session-tree append/fork, compaction trigger), `pico_sdk` (`AgentSession` behaviour, extension registration and hooks).
+- **Prior art.** None — this is a fresh codebase. Use `pytest` with `pytest-asyncio`; the fake provider returns scripted streams.
+
+## Out of Scope
+
+- `pico_tui` (the terminal UI) — a follow-up spec.
+- MCP, sub-agents, plan mode, and local to-do tracking — future plugins.
+- Native provider adapters beyond the OpenRouter gateway — future plugins.
+- Sandboxing / containerization of bash execution.
+- Telemetry.
+- Multi-session management beyond single-session persistence.
+
+## Further Notes
+
+- Build order: `pico_ai` → `pico_core` → `pico_sdk`.
+- First milestone: headless `pico run "…"` works end-to-end (prompt → loop → tools → persisted session).
+- Respect ADR-0001 (monorepo split) and ADR-0002 (tree-based session) throughout.

pico_cli-0.1.0/.scratch/pico-tui/spec.md

@@ -0,0 +1,70 @@
+---
+title: Terminal UI (interactive chat)
+labels:
+  - ready-for-agent
+---
+
+> **Status note (2026-09-30):** implemented and since exceeded — the TUI is now
+> a full Textual + Rich app (`/help`, `/history`, `/compact`, `/model`,
+> `/skills`, `/fork`, `/undo`, `/quit`, todo panel, status bar, pickers).
+> The "empty scaffold / deferred rendering" framing below is historical.
+> Kept for history — do not re-implement.
+
+# Terminal UI (pico_tui)
+
+## Problem Statement
+
+The headless `pico run "…"` command works end-to-end, but every invocation is a single prompt with no interactive loop. A developer who wants to explore a repo interactively — ask follow-ups, watch tool calls happen, rewind after a bad turn, compact when context grows — needs an interactive terminal interface, not one-shot commands.
+
+Today `pico_tui` is an empty scaffold: no REPL, no streaming view, no command handling.
+
+## Solution
+
+Build the **terminal UI view** in `pico_tui` on top of the existing `AgentSession` API, so that `pico-chat` launches an interactive, streaming session:
+
+- A prompt loop (`pico> `) that streams the agent's response token-by-token.
+- Visible tool activity: bash commands echoed before execution, other tool calls shown with name + arguments.
+- Slash commands: `/help`, `/compact [instructions]`, `/fork <node-id>`, `/quit`.
+- The session is persisted on exit and resumable via `--session`.
+
+The TUI is a thin view over `pico_sdk`: it renders `LoopEvent`s and dispatches slash commands, and does **not** reimplement the loop, tools, or persistence. Per ADR-0001 it sits at the top of the one-way chain `pico_ai ← pico_core ← pico_sdk ← pico_tui`.
+
+## User Stories
+
+1. As a developer, I want an interactive prompt loop, so that I can have a back-and-forth conversation with the agent.
+2. As a developer, I want responses to stream token-by-token, so that I can watch output as it is generated.
+3. As a developer, I want bash commands echoed before they run, so that I can audit what the agent is doing.
+4. As a developer, I want other tool calls (read/write/edit) shown with their arguments, so that I can see what the agent is doing.
+5. As a developer, I want a `/help` command, so that I can discover the available commands.
+6. As a developer, I want `/compact [instructions]`, so that I can manually compact the context with steering text.
+7. As a developer, I want `/fork <node-id>`, so that I can rewind to an earlier node and start a new branch interactively.
+8. As a developer, I want `/quit`, so that I can save the session and exit cleanly.
+9. As a developer, I want to resume a prior session with `--session <id>`, so that I can continue where I left off.
+10. As a developer, I want the same flags as `pico run` (`--model`, `--allow-bash`, `--cwd`), so that I can configure an interactive session the same way.
+
+## Implementation Decisions
+
+- **Thin view.** The TUI renders `LoopEvent`s and dispatches slash commands; the agent loop, tools, session tree, and persistence all come from `pico_sdk` unchanged. Interactive features belong here, not in the core.
+- **Shared provider factory.** `pico_sdk.providers.create_provider()` builds the OpenRouter provider from the configured env var; both `pico run` and `pico-chat` use it (one source of truth for provider wiring).
+- **Streaming.** The REPL iterates `AgentSession.stream(prompt)` and writes text chunks immediately (no buffering).
+- **Blocking input on a thread.** `input()` runs via `asyncio.to_thread`, so the event loop is not blocked while a response streams.
+- **Command vocabulary.** `/help` (aliases `/h`, `/?`), `/compact [instructions]`, `/fork <node-id>`, and `/quit` (aliases `/exit`, `/q`). Any other non-empty line is sent to the agent as a prompt.
+- **Separate entry point.** `pico-chat` console script, distinct from `pico run`, preserving the one-way dependency (pico_sdk does not import pico_tui).
+
+## Testing Decisions
+
+- **Pure functions first.** `parse_line` (input → command/prompt) and `render_event` (`LoopEvent` → display string) are unit-tested directly.
+- **REPL seam.** `TUI` accepts injected `input_fn` and `write` callables, so the interactive loop is tested with a scripted input sequence and a captured output buffer, driven by the same scripted fake provider used for the headless agent.
+- **Live smoke.** A piped-input run (`"say hi"` then `/quit`) against a real fast model confirms the end-to-end loop.
+
+## Out of Scope
+
+- Rich terminal rendering (colors, spinners, curses/Textual) — deferred.
+- A `/history` or node-browser command for discovering node ids — `/fork` currently takes an id directly.
+- Multi-panel or split layouts.
+- Any change to the agent loop, tools, or persistence — those live in `pico_core`/`pico_sdk`.
+
+## Further Notes
+
+- `pico run` remains the headless path; `pico-chat` is the interactive path.
+- Follow-up specs may add richer rendering and node discovery without touching the core.

pico_cli-0.1.0/.scratch/trace-view/01-assistant-duration.md

@@ -0,0 +1,16 @@
+# 01 — Assistant stream timing (`duration_ms`)
+
+**What to build:** measure provider-stream wall-time in `AgentLoop.stream()`
+(`packages/pico_core/src/pico_core/fsm.py`) and persist it as
+`duration_ms: float | None = None` on `AssistantPayload`
+(`packages/pico_core/src/pico_core/session.py`). `None` means "unknown"
+(old sessions, unmeasurable runs) and renders as `—`.
+
+**Blocked by:** nothing.
+
+**Status:** ready-for-agent
+
+- [ ] `AssistantPayload` gains `duration_ms: float | None = None`; old JSONL session files still validate and load.
+- [ ] The loop records a monotonic start before `provider.stream(request)` and stamps the appended `AssistantPayload` with elapsed ms (both tool and non-tool turns).
+- [ ] Interrupted/error streams still append with a measured (partial) duration or `None` — never crash timing.
+- [ ] Fake-provider tests assert a non-negative `duration_ms` on the appended assistant node.

pico_cli-0.1.0/.scratch/trace-view/02-row-assembly.md

@@ -0,0 +1,18 @@
+# 02 — Trace row assembly (pure function)
+
+**What to build:** a pure function mapping the active branch (`list[Node]`)
+to trace rows: `time (HH:MM:SS from node.timestamp)` | `kind` |
+`summary (one line, ~80ch, same truncation as the history picker)` |
+`status (ok/error from is_error, plus bash exit code where parseable)` |
+`tokens (assistant total, else blank)` | `duration (computed
+result.timestamp − request.timestamp paired by tool_call_id; assistant
+duration_ms; else blank)`.
+
+**Blocked by:** 01 — Assistant stream timing (for the assistant-duration branch).
+
+**Status:** ready-for-agent
+
+- [ ] One tested function, no Textual/Rich dependency (like `commands.parse_line`).
+- [ ] Tool durations pair request/result by `tool_call_id`; orphan results (missing request, e.g. old/odd trees) show blank, never crash.
+- [ ] Bash exit codes reuse the existing result-parsing rule (`[exit code: N]` suffix).
+- [ ] Non-assistant token cells and non-duration rows are blank (`—`/`—`), never estimated.

pico_cli-0.1.0/.scratch/trace-view/03-overlay.md

@@ -0,0 +1,18 @@
+# 03 — Trace view overlay (`Ctrl+T`, `/trace`)
+
+**What to build:** a full-screen TUI overlay (`TraceViewScreen`) rendering
+rows from 02 for the active branch: snapshot on open (not live), `r`
+re-snapshots, `e` toggles errors-only, typing filters (substring over the
+summary, reusing the `PickerScreen` filter bar), `↑/↓` moves, `Enter`/`Esc`
+dismisses. Open via `Ctrl+T` binding plus `/trace` slash command (parsed in
+`commands.py`, dispatched in `app.py`, listed in `HELP_TEXT`).
+
+**Blocked by:** 02 — Trace row assembly.
+
+**Status:** ready-for-agent
+
+- [ ] `Ctrl+T` opens, `Esc`/`Ctrl+T` closes; `/trace` opens the same overlay; `/help` documents both.
+- [ ] Overlay shows a snapshot taken on open; `r` refreshes from the current active branch (fork/undo-safe: no nodes are mutated).
+- [ ] `e` toggles errors-only (`is_error` rows); the filter bar narrows by summary text; the two compose.
+- [ ] Empty sessions render a `(no nodes)` state; 80-col terminals show all six columns without wrapping.
+- [ ] TUI tests drive it with `FakeProvider` sessions (open, filter, errors-only, refresh, dismiss).

pico_cli-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked as local markdown files under `.scratch/<feature>/`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage labels are: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` and `docs/adr/` at the repo root; agents read `CONTEXT.md` before starting work and treat ADRs as authoritative recorded decisions. See `docs/agents/domain.md`.

pico_cli-0.1.0/CONTEXT.md

@@ -0,0 +1,29 @@
+# Context
+
+The domain vocabulary for **pico**, a Python CLI coding agent with a hardcoded core and curated extensions (Claude Code-style, see ADR-0003).
+
+## Glossary
+
+- **Agent** — the autonomous coding agent itself. It acts on its own, without asking for approval at each step (informally, *yolo mode*).
+- **Session** — one persisted coding session, represented as a tree of nodes.
+- **Node** — an immutable, append-only unit of event data in a session. Each node carries an id, a pointer to its parent, a timestamp, and a payload. Once written, a node is never edited or deleted — only built upon.
+- **Payload** — the content of a node: a **user** message, an **assistant** message, a **tool request**, a **tool result**, or a **compaction summary**.
+- **Branch** — a timeline: the sequence of nodes from the root to a leaf. A session can hold many parallel branches.
+- **Fork** — rewinding to an earlier node and starting a new branch from it (for example, after a change that broke the codebase).
+- **Turn** — one user message plus the agent's full response to it, including any tool requests it makes.
+- **Tool** — a capability the agent can invoke. The core tools are **read**, **write**, **edit**, **grep**, **fetch**, **websearch**, **bash**, **todo**, and **task**.
+- **Todo tool** — the agent-facing `todo` tool (actions `add` / `update` / `list` / `clear`) backed by a shared in-memory **todo list**; statuses are `pending`, `in_progress`, `completed`.
+- **Sub-agent** — a child agent loop spawned by the parent through the model-invoked `task` tool. It runs on its own session (persisted as its own file) with restricted tools, and only its final summary returns to the parent.
+- **Tool request** — the agent asking to run a tool.
+- **Tool result** — the output returned by running a tool.
+- **Compaction** — summarising older context so the session fits within the model's context window.
+- **Context window** — the token budget of the model in use.
+- **Reserve tokens** — the portion of the context window held back for the model's own response.
+- **Provider** — an LLM backend. Every provider is reached through a single gateway and exposed as one unified **AI call**.
+- **Adapter** — one Python module per provider (`pico_ai/providers/`) converting that backend's wire format to the app's default event shape. The registry is a hardcoded host-owned list, not a plugin API (see ADR-0004).
+- **AI call** — the unified request/response shape used to talk to any provider.
+- **Headless** — running the agent programmatically (as a library) with no terminal UI.
+- **Hook** — a curated, observe-only lifecycle callback (`session_start`, `pre_tool_use`, `post_tool_use`, `post_tool_failure`). Hooks cannot mutate arguments/results or veto execution.
+- **Skill** — a model-invoked `SKILL.md` markdown file (name + trigger description + instructions) discovered from `~/.pico/skills/*/SKILL.md` and `~/.agents/skills/*/SKILL.md` (plus project-local override) and inlined into the system prompt.
+- **Trace view** — a full-screen overlay listing one row per node on the active branch.
+- **Trace row** — one line in the trace view showing a single node's time, kind, summary, status, tokens, and duration.

pico_cli-0.1.0/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,80 @@
+# Context Status Bar Implementation Summary
+
+## Overview
+Added a context status bar widget to the PicoCLI TUI that displays:
+- Provider name (e.g., "OpenRouter")
+- Model name (e.g., "nvidia/nemotron-3.5-lightning:free")
+- Thinking indicator (shown when the model is reasoning)
+- Context window progress bar (fills as context fills, color-coded by usage level)
+- Current token count (formatted with commas, e.g., "38,932")
+
+## Files Modified
+
+### 1. `packages/pico_core/src/pico_core/fsm.py`
+- Added public `estimate_tokens()` method to `AgentLoop` class
+- This exposes the private `_estimate_tokens()` functionality
+
+### 2. `packages/pico_sdk/src/pico_sdk/session.py`
+- Added `provider_name` property to `AgentSession` class
+  - Extracts provider name from the provider class name
+  - Returns "OpenRouter" for OpenRouterProvider
+- Added `context_window` property to `AgentSession` class
+  - Returns the context window size from the agent loop
+- Added `estimate_tokens()` method to `AgentSession` class
+  - Returns current estimated token count from the agent loop
+
+### 3. `packages/pico_tui/src/pico_tui/status_bar.py` (NEW FILE)
+- Created `ContextStatusBar` widget extending Textual's `Static`
+- Features:
+  - Displays provider | model information
+  - Shows "thinking" indicator in yellow italic when active
+  - Renders a 20-character progress bar for context window usage
+  - Color-codes the progress bar:
+    - Green: 0-50% usage (░ character)
+    - Yellow: 50-70% usage (▒ character)
+    - Orange: 70-90% usage (▓ character)
+    - Red: 90-100% usage (█ character)
+  - Shows token count with comma formatting in cyan
+- Methods:
+  - `on_mount()`: Renders initial display after widget mount
+  - `update_info()`: Updates all status information
+  - `set_thinking()`: Updates thinking state
+  - `_update_display()`: Renders the status bar with Rich Text
+
+### 4. `packages/pico_tui/src/pico_tui/app.py`
+- Imported `ContextStatusBar` widget
+- Added CSS styling for `#status-bar`:
+  - Docked to bottom
+  - Height: 1 line
+  - Background: $surface color
+  - Padding: 0 1
+- Added `ContextStatusBar` to `compose()` method after Input widget
+- Added `_update_status_bar()` method to update the status bar with current session info
+- Updated `on_mount()` to call `_update_status_bar()` on initialization
+- Updated `_run_prompt()` to call `_update_status_bar()` when streaming starts
+- Updated `_stream_worker()` to call `_update_status_bar()` when streaming completes
+
+### 5. `tests/test_status_bar.py` (NEW FILE)
+- Added 3 tests for the ContextStatusBar widget:
+  - `test_status_bar_initialization`: Verifies default values
+  - `test_status_bar_stores_info`: Verifies info storage
+  - `test_status_bar_set_thinking`: Verifies thinking state updates
+
+## Test Results
+All 92 tests pass successfully, including:
+- 19 existing TUI tests
+- 3 new status bar tests
+- All other existing tests remain passing
+
+## Usage
+The status bar automatically appears below the input bar in the TUI and updates:
+- On application startup (shows initial provider, model, and 0 tokens)
+- When a prompt is submitted (shows "thinking" indicator)
+- When streaming completes (updates token count and hides "thinking")
+- When the model changes via `/model` command
+
+The status bar provides real-time visibility into:
+- Which AI provider and model is being used
+- Whether the model is currently thinking/reasoning
+- How much of the context window is being used
+- The exact token count in the current context

pico_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arya-Ojha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.