ooooooooo. o8o
`888 `Y88. `"'
888 .d88' .ooooo. ooo. .oo. .oooooooo oooo oooo oooo ooo. .oo.
888ooo88P' d88' `88b `888P"Y88b 888' `88b `888 `888 `888 `888P"Y88b
888 888ooo888 888 888 888 888 888 888 888 888 888
888 888 .o 888 888 `88bod8P' 888 888 888 888 888
o888o `Y8bod8P' o888o o888o `8oooooo. `V88V"V8P' o888o o888o o888o
d" YD
"Y88888P'
Penguin is an open-source coding agent built on a scalable cognitive architecture runtime.
It is designed for long-running, tool-using, multi-agent software workflows: from
interactive coding in the TUI to persistent sessions, subagent delegation, and
API-driven automation. Penguin combines a coding-focused agent runtime with durable
state, workspace-aware tools, and multiple interfaces on top of the same core.
Why Penguin
- Purpose-built for software engineering workflows, with coding tools, sessions, and subagents.
- Stateful runtime: sessions, checkpoints, tool history, and replayable transcripts.
- Context Window Manager: long sessions stay coherent through category-aware token budgeting,
truncation, and replay, preserving recency and message-category priorities across long-running sessions.
- Multi-agent orchestration: planner/implementer/QA patterns, subagents, and scoped delegation.
- Multiple surfaces: TUI, CLI, web API, and Python client on the same backend.
- OpenCode-compatible TUI path: Penguin web/core now powers an OpenCode-style terminal UX.
Quick Start
# Recommended: use uv for less environment/package-management hassle,
# faster installs/syncs, and support for this repo's safer dependency workflow.
uv tool install penguin-ai
# Alternative: plain pip still works
pip install penguin-ai
# Set a model provider key (OpenRouter is the easiest starting point)
export OPENROUTER_API_KEY="your_api_key"
# Launch Penguin
penguin
uv is the recommended path for most users: it is generally faster than pip, keeps
Python environment management simpler, and supports this repo's exclude-newer safety rail
for dependency resolution in development workflows.
Other entrypoints:
penguin - interactive Penguin TUI launcherptui - direct TUI aliaspenguin-cli - headless CLI for automation and scriptspenguin-web - FastAPI server for web/API usage
Web Server Logs
penguin-web writes one server log file per web server run by default:
{PENGUIN_WORKSPACE:-~/penguin_workspace}/server-logs/penguin-web-<timestamp>-<pid>.txt
The log file includes Penguin startup/application logs plus Uvicorn error and access
logs, with per-file rotation enabled. Override the directory, force a specific file,
or disable this behavior with:
export PENGUIN_WEB_LOG_DIR="/path/to/server-logs"
export PENGUIN_WEB_LOG_FILE="/path/to/logs.txt"
export PENGUIN_WEB_LOG_ENABLED=false
What You Get
- Coding workflow tools: file reads/writes/diffs, shell commands, test execution, search,
code analysis, and background process management.
- Context Window Manager: category-based token budgets, multimodal truncation, and live usage
reporting to keep histories within model limits. This supports theoretically infinite sessions.
- Persistent memory and file-backed context: declarative notes, summary notes,
context/
artifacts, docs cache, and daily journal continuity.
- Multi-agent execution: isolated or shared-context subagents, delegation, planner/
implementer/QA patterns, and background task execution.
- Browser and research support: web search plus browser automation for documentation,
web workflows, and UI testing.
- Session durability: checkpoints, rollback, branching, transcript replay, and long-running
task continuity.
- Project and task orchestration backed by SQLite, including todo tracking and Run Mode.
- Native and gateway model support across OpenAI, Anthropic, and OpenRouter by default, with LiteLLM available as an optional extra.
Interfaces
Penguin exposes the same runtime through several surfaces:
penguin / ptui - terminal-first coding workflow with streaming, tools, and session navigation.- The Penguin TUI reports active-session status through OSC 7501 to supporting terminals, independently of notification settings. Compatible terminal titles show run state; optional alerts select cmux/iTerm2/WezTerm/Kitty protocols with a bell fallback for Apple Terminal. Completion alerts include a short response preview when notification details are enabled.
penguin-cli - scriptable CLI interface for prompts, tasks, config, and automation.penguin-web - REST + WebSocket/SSE backend for the TUI and custom integrations.- Python API -
PenguinAgent, PenguinClient, and PenguinAPI for embedding Penguin in code.
Web/API Surface Notes
-
Trusted Link callers can opt into durable chat requests for deduplicated execution and persisted result lookup.
-
Isolated runtimes can use run-scoped Link inference without a server-wide service secret.
-
Task/project endpoints now expose current runtime state rather than only legacy task summaries.
- Task payloads include
status, phase, dependencies, dependency_specs, artifact_evidence, recipe, metadata, and clarification_requests where relevant.
-
POST /api/v1/tasks/{task_id}/execute now routes through RunMode, so non-terminal outcomes like waiting_input and clarification-needed results are preserved instead of being flattened into fake completion/failure states.
-
POST /api/v1/tasks/{task_id}/clarification/resume answers the latest open clarification request and resumes execution through the same RunMode lifecycle.
-
Session-goal endpoints under /api/v1/session/{session_id}/goal persist one
durable objective per saved session and execute it through bounded RunMode steps.
Goal control and run operations use explicit 404, 409, and 422 responses
for missing state, lifecycle conflicts, and invalid input.
-
GET /api/v1/events/sse streams OpenCode-compatible events and now includes session-scoped clarification status visibility for web clients.
-
PenguinAPI.run_task(...) and PenguinAPI.resume_with_clarification(...) are aligned with the web route behavior so programmatic callers see the same lifecycle truth.
These surfaces are still under active audit, but the current direction is explicit: web/API consumers should receive the same task/clarification truth that the backend runtime uses internally.
Quick Python Example
from penguin import PenguinAgent
with PenguinAgent() as agent:
response = agent.chat("Summarize the current task charter")
print(response["assistant_response"])
Installation
Penguin requires Python 3.11 through 3.12. The minimum version allows installing security-patched Pillow 13.
Recommended
# Default install: CLI + web runtime + OpenCode TUI launcher support
pip install penguin-ai
# Compatibility alias for older install commands
pip install penguin-ai[web]
# Compatibility alias for older install commands
pip install "penguin-ai[tui]"
# Legacy Textual prototype / experimental UI support
pip install "penguin-ai[legacy_tui]"
# Full feature set
pip install penguin-ai[all]
Development
git clone https://github.com/Maximooch/penguin.git
cd penguin/penguin
# Safe default: respects `[tool.uv] exclude-newer = "7 days"`
uv sync
# Editable dev/test install via pip still works if you prefer it
pip install -e .[dev,test]
Safer uv Installs
This repo configures uv to ignore package releases newer than 7 days by default:
[tool.uv]
exclude-newer = "7 days"
That gives the ecosystem a little time to detect and yank malicious releases before you
pull them in. It's a useful guardrail, not a complete supply-chain strategy.
Convenience shortcuts:
make sync-safe # use the default 7-day delay
make lock-safe # refresh lockfile with the 7-day delay
make lock-latest # intentionally override and resolve newest compatible releases
make sync-latest # resolve + sync using newest compatible releases
Under the hood, the latest targets override the project default with --exclude-newer 2999-12-31T23:59:59Z.
Extras
| Extra | Description |
|---|
[tui] | Compatibility alias; default install already includes TUI launcher runtime |
[web] | Compatibility alias; default install already includes web runtime |
[legacy_tui] | Legacy Textual prototype / experimental UI support |
[llm_litellm] | Optional LiteLLM support for legacy/custom gateway workflows |
[memory_faiss] | FAISS vector search + embeddings |
[memory_lance] | LanceDB vector database |
[memory_chroma] | Compatibility alias (ChromaDB disabled pending upstream security fixes) |
[mcp] | Model Context Protocol client/server dependencies (Python 3.10+ for the MCP SDK) |
[browser] | Browser automation support. Installs PyDoll fallback; browser-harness must be installed from a local/source checkout because it is not published on PyPI yet. |
[pydoll] | PyDoll browser automation fallback only |
[all] | Everything above that is available from PyPI |
Browser-harness is Penguin's preferred browser_* backend on this branch, but it
is currently a local/source dependency rather than a PyPI package. For local
browser-harness testing, install Penguin's browser extra for the PyPI-available
fallback and then install browser-harness into the same environment from a source
checkout:
pip install "penguin-ai[browser]"
pip install -e /path/to/browser-harness
If browser-harness is unavailable, the pydoll_browser_* tools remain available
as the compatibility fallback.
TUI Runtime
The Penguin TUI launcher supports both development and packaged installs.
- In a source checkout,
penguin prefers local penguin-tui/packages/opencode sources.
- Outside a source checkout, it bootstraps a cached sidecar binary under
~/.cache/penguin/tui.
- Stable installs prefer a sidecar that matches the installed Penguin version.
- You can override the source or binary path when needed:
# Force local source mode
export PENGUIN_OPENCODE_DIR="/path/to/penguin/penguin-tui/packages/opencode"
# Force a specific sidecar binary
export PENGUIN_TUI_BIN_PATH="/path/to/opencode"
You can also override the release endpoint for staging/testing with PENGUIN_TUI_RELEASE_URL.
Common Commands
/models # interactive model selector
/model set <MODEL_ID> # set a specific model
/stream on|off # toggle streaming
/checkpoint [name] # save a checkpoint
/checkpoints [limit] # list checkpoints
/rollback <checkpoint> # restore a checkpoint
/tokens # token usage summary
/run task "Name" # start a specific task
/goal <objective> # save a session goal and start execution
/goal status # show the current session goal
/goal pause|resume # pause it, or resume execution
/goal run # restart an active goal after a non-terminal return
/goal clear # remove the session goal
/247 ... # exact alias for the corresponding /goal command
/config --global set git.attribution.prompt false # disable Git co-author guidance
Session goals require a persisted session. /goal <objective> stores durable
lifecycle state, then starts RunMode execution. With no user-configured
max_iterations, timeout_seconds, or goal token_budget, Penguin adds no
local iteration, wall-clock, or token stop. Replacing an unfinished goal requires
--replace. /247 is only a slash-command alias for /goal; the headless
--247 / --continuous flag still means continuous RunMode and is a different
interface. Session-goal run ownership is process-local in this release, so a
shared conversation store must be served by one Penguin web process rather than
multiple workers.
Penguin prompts for
Co-authored-by: penguin-agent[bot] <penguin-agent[bot]@users.noreply.github.com>
on agent-created commits by default. This is configurable prompt guidance only;
it does not modify Git identity or rewrite commits.
Architecture
Penguin is structured as a runtime for long-lived agent workflows.
PenguinCore handles construction, delegation, and compatibility methods.penguin.core_runtime owns extracted runtime helpers for processing, model/provider behavior, checkpoints, token usage, action mapping, OpenCode/TUI bridging, diagnostics, and compatibility shims.Engine runs the reasoning loop, model calls, and tool orchestration.ConversationManager persists sessions, checkpoints, and conversation state.ContextWindowManager manages long-session token budgets with category-aware truncation,
multimodal handling, and replay-friendly context continuity.ToolManager and ActionExecutor run workspace-aware tools and action pipelines.- CLI, TUI, web, and Python APIs all sit on top of the same backend services.
Penguin's long-term direction is a scalable cognitive architecture runtime: a persistent
agent kernel with userland surfaces for sessions, tools, orchestration, and observability.
Read more:
architecture.mdcontext/tasks/Penguin_SCAR_80_20_Roadmap.mdcontext/tasks/tui-opencode-implementation.md
Version Highlights
v0.9.3
- Hardened long-running execution with stale-tool-loop recovery, truncated-output continuation, quiet process waits, and bounded process I/O.
- Added authenticated A2A serving with durable task receipts and read-only conversation archive lookup.
- Strengthened Link execution authority, approval enforcement, hosted environments, native-tool isolation, and durable request cancellation.
- Improved context/cache stability with request-local context epochs, turn-scoped Codex cache routing, and pooled transport.
- Added TUI terminal status/response notifications, provider-advertised service tiers, and faster workspace file search.
- Updated security-sensitive dependencies and aligned the supported runtime with Pydantic 2.11.3–2.x (Python 3.10–3.12).
v0.9.2
- Added durable session-scoped
/goal and /247 workflows with persisted lifecycle state, RunMode execution, API/TUI controls, and truthful partial or blocked outcomes.
- Added native Modal Auto Endpoint and RunInfra providers, plus Link-backed personal subscription inference with scoped execution authority and per-request permission policies.
- Stabilized multi-agent execution across async tool dispatch, executor ownership, admission policy, child model selection, cancellation, message delivery, and execution isolation.
- Reduced live-output latency by emitting assistant deltas immediately and batching runtime-event ledger persistence outside the SSE hot path.
- Added a packaged observability dashboard for sessions, tasks, context, cost, performance, reliability, runtime events, and server logs.
- Simplified first-run onboarding, refactored prompt composition, exposed native session todo tools, resolved dependency security alerts, and moved the supported Python range to 3.10–3.12.
v0.9.1
- Added day-one GPT-5.6 support through Penguin's OpenAI/Codex OAuth catalog path, including Sol, Terra, and Luna when advertised and provisioned for the authenticated account.
- Preserved model-specific reasoning metadata through request execution and mapped Codex
ultra mode to the OpenAI-safe max wire effort.
- Rejected unsupported reasoning variants before REST/WebSocket requests can persist or execute them.
- Preserved explicit reasoning opt-outs and supported configured efforts across catalog hydration and OAuth token refreshes.
- Added a dedicated CLI ACBRA decomposition campaign, with broader CLI ergonomics work sequenced after structural stabilization.
v0.9.0
- Completed the ACBRA core-runtime decomposition campaign:
PenguinCore is now a thin compatibility/orchestration facade over focused penguin.core_runtime modules.
- Added a durable runtime event ledger and canonical runtime-event envelope projection for web/TUI clients, giving downstream surfaces replayable and normalized runtime state.
- Closed the Penguin TUI upstream-adoption campaign through Phase 10, including stronger OpenCode-compatible event frames, prompt/session compatibility, notification controls, backend command registry foundations, provider/model catalog state, and session hydration state.
- Hardened the TUI around prompt context handling, paste handling, malformed tool input, inline tool errors, live assistant turn ordering, running-state submit blocking, model selection, session lists, usage telemetry, and startup performance.
- Expanded multi-agent/tool exposure for Responses-style providers and improved runtime compatibility edges across sessions, web, and TUI surfaces.
- Added per-run web server file logging with configurable log directory/file controls for easier operational debugging.
v0.8.1
- Fixed Python 3.9 import compatibility for MCP configuration by avoiding a runtime PEP 604 union type alias.
v0.8.0
- Shipped three weeks of daily dogfooding hardening across Penguin's core runtime, tool execution, task orchestration, and TUI/web surfaces.
- Added ordered batch tool execution and process-runtime foundations for more reliable multi-step agent workflows.
- Improved native tool-call runtime behavior across provider adapters, transcript replay, tool-result handling, and action execution metadata.
- Tightened RunMode, project-task, and clarification flows so API/web clients preserve non-terminal runtime truth instead of flattening everything into fake success/failure states.
- Continued OpenCode-compatible TUI integration work, including better event ordering, session scoping, sidecar packaging, and launcher behavior.
- Strengthened local web/API security and operational surfaces around auth, settings, credentials, provider routes, SSE/WebSocket behavior, and GitHub integration.
- Expanded test coverage around provider contracts, streaming, session isolation, task state, permission/question flows, package exports, and TUI launcher behavior.
- Added and updated assurance and architecture documentation for the next phase of core refactoring and testing discipline.
v0.7.0
- Hardened the native tool-call runtime across provider adapters, transcript replay, tool-result adjacency, and TUI event ordering.
- Shipped a safer local web/TUI auth flow with protected HTTP, SSE, and WebSocket bootstrap paths plus stronger upload and webhook guards.
- Expanded project bootstrap and task orchestration surfaces across TUI, web/API routes, and Run Mode while preserving non-terminal runtime truth.
- Added OpenAI/Codex fast-mode service-tier support and improved OAuth-backed Codex/latest-model access.
- Added Penguin TUI themes and defaulted the packaged TUI experience to the Emperor theme.
v0.6.3
- Expanded native OpenAI / Codex integration, including stronger Responses API handling and OAuth-backed Codex response support.
- Improved OpenAI-compatible provider support and model/runtime normalization for native and gateway flows.
- Better handling of tool-only OpenAI/Codex turns and Responses-style tool calls in the runtime loop.
- Continued runtime/docs alignment work across task clarification, dependency-policy, and public surface verification.
OpenAI speed modes in the TUI: /fast requests priority; /ultrafast requests
ultrafast. Both support on, off, and status, subject to model/account access.
See speed-mode configuration.
Documentation
Contributing
git clone https://github.com/Maximooch/penguin.git
cd penguin/penguin
pip install -e .[dev,test]
pytest -q
Support
License
Licensing in this repository is split by component:
penguin/ and the main Penguin runtime are licensed under the GNU Affero General Public
License v3.0 or later.penguin-tui/ contains OpenCode-derived TUI code that remains MIT-licensed; see
penguin-tui/LICENSE.- Read the official GNU AGPL v3 text
Enterprise licensing without AGPL copyleft requirements is under consideration. If
you are interested, contact [email protected].
Acknowledgments
Built upon insights from:
For long-running shell commands, see managed processes.
Completed handles are retired under capacity pressure while logs and cached retry
results remain available; live commands keep their slots.
Workspace-mode file writes outside the active project, including sibling worktrees,
request approval in the TUI. See tool permissions
for approval scope and limitations. Use /permissions in the TUI to enable
Full access for the current session and avoid per-file approval prompts.
