LIUTod/scream-code

A local agent with zero remote data behavior — write code, run tasks, research, code or work as you please.

English | 简体中文

❤️Sponsor

Click to collapse

todapi — a high-value API gateway. DeepSeek and other mainstream models from as low as 10% of list price, reached through one unified gateway: pay-as-you-go, one API key for multiple models. Powered by tier-one vendor resources with stable routes and strong value. Price: DeepSeek and more from 10% of list price Access: one gateway, one key — switching models no longer means switching providers Get started: sign up at todapi.work Thanks to todapi for sponsoring this project ❤️

---

Installation

npm install -g scream-code

[!NOTE] Requires Node.js >= 22. Git recommended. Same command installs and updates. No native build steps and no dependency install scripts: the local embedding engine runs on WebAssembly. The first use of the knowledge/memory vector features downloads a ~53MB model into ~/.scream-code/cache (progress is shown, and the download verifies its checksum before use).

Quick Start

scream            # terminal UI
scream --auto     # auto permission mode
scream -y         # auto-approve mode

On first launch Scream walks you through model setup (/config — pick the shortcut provider directory, a custom DIY setup, or image generation). 130+ providers built in — or point it at any OpenAI-compatible endpoint with /config diy. Switch models anytime with /model, no restart needed — or use /model diy to give each sub-agent its own model, letting every model do what it does best. Generate or edit images the same way: run /config image once, then just ask for a picture (the /image skill).

When Scream wants to modify files or run commands, an approval panel pops up — pick a number, press Enter.

Features

• Goal Loop — autonomous, goal-driven execution with an independent judge agent. Rejections must name concrete gaps; evidence gaps self-repair for up to 3 rounds, subjective calls park for your decision (with a written report), and token/time budgets bound the loop.
• TUI Sidebar — five live panels: workspace Git diff summary (green adds / red deletes), per-session token accounting (cache-hit / cache-miss / output), 9 sub-agent slots with real-time states (idle / working / outputting / messaging / reworking / asking), Goal status with judge state (awaiting / judging / adjudicated), and a Network Hub — the measured provider response time plus round trips to a few well-known endpoints, probed only while the sidebar is visible, every 30 seconds.
• Wolfpack — unlimited parallel sub-agents (coder / explore / plan / verify / reviewer / oracle / worker / writer / designer).
• Subagent Collaboration — delegate to specialist sub-agents and stay in control: they ask the lead agent for guidance mid-task instead of guessing when blocked, request a handoff when a different specialist fits, take mid-task redirects or follow-up notes, return structured JSON when asked, and can be confined to a safe mode (read-only / edit-only / commands-allowed) so they never overstep your limits.
• Bot Mode (/bot) — unattended execution: reversible work (reads, in-workspace edits, read-only commands) runs freely, while irreversible actions (push / publish / delete / sensitive files / unclassified operations) are automatically denied and queued for your review — with the reason fed back to the model so it stops retrying.
• Persistent Memory — structured pain-point memory with FTS5 full-text + tag + vector retrieval, shared across sessions.
• Local Knowledge Graph — SAG-based visual knowledge base for multi-hop reasoning; import your own docs anytime.
• RLM Mode — persistent Python workspace for long-running tasks; rlm() spawns recursive sub-agents straight from code, always through the coder profile, unlimited by default and cap-limited per session with /rlm-max-depth. Every rlm() call is a real sub-agent run — it consumes tokens like any other delegation.
• Script Mode — on by default: the model can run JavaScript in a sandbox that calls the other tools for it, so batch work (dozens of files/pages, filter-then-report) finishes in one round trip — only the script's summary enters the conversation; /script toggles it.
• Session Trace — /trace exports any session as a self-contained, offline interactive HTML timeline.
• Context Search — /search (Ctrl+Shift+F) full-screen keyword search over the conversation.
• High Cache Hit Rate — per-session HitR in the status bar, tuned across compatible protocols to maximize cache hits without compromising quality.
• MCP / Skills / 130+ providers — all DIY-configurable; ships with browser automation and macOS desktop automation.
• Self-Evolving Plugins — a built-in ManagePlugin tool lets the agent find, make, and install add-on skills/MCP servers itself and hot-apply them to the running session: nothing executes until an approved activate, a circuit breaker reclaims a plugin after repeated failures, immune memory warns before reinstalling a source that already broke, and upgrades keep a rollback-ready backup.
• Remote Control — drive Scream from WeChat or Feishu/Lark via the native /line channel: text, images and files both ways, plus /status, /model, /compact, /new without the desktop client.

Slash Commands

Type / in the input to browse. All 55 commands:

Full command reference (click to expand)

Command	Description
Modes & execution
/auto	Toggle auto permission mode
/yes (/yolo)	Toggle auto-approve mode
/ask	Toggle read-only Q&A mode
/bot	Unattended bot mode: reversible actions auto-approve, irreversible ones park for review
/goal [objective]	View/manage auto goals
/wolfpack (/wp)	Toggle wolfpack mode — auto-approve + batch concurrency
/rlm	RLM mode: persistent Python workspace; rlm() spawns real recursive subagents (coder profile)
/rlm-max-depth [N]	Show or set the RLM recursion depth limit (0 = unlimited; the default is unlimited)
/script	Script mode: run JavaScript in a sandbox that batches tool calls (on by default)
/plan	Toggle plan mode
/fusionplan (/fp)	Fusion plan mode (multi-agent parallel planning)
/btw	Quick question without interrupting the conversation
/eval	Run end-to-end tests (agent health check)
Session
/new (/clear)	Start a new session
/sessions (/resume)	Browse and restore sessions
/compact	Compact conversation context
/fork	Copy session into a new branch
/title (/rename)	Set or show session title
/revoke [N]	Undo the last N conversation rounds
/export-md (/export)	Export session as Markdown
/export-debug-zip	Export session as debug ZIP
/status	Show session and runtime status
/usage	Show token usage and context window
Memory & knowledge
/memory (/memo, /mem) [query]	Browse, search, inject memory memos
/knowledge (/know) [query]	Manage local knowledge base
Models & configuration
/model [alias]	Switch LLM model
/config (/login)	Configure model services: quick provider pick, custom DIY setup, or image generation
/config image	Configure image generation (provider, URL, key, model)
/logout (/disconnect)	Remove configured models
/language (/lang)	Switch interface language
/theme	Set terminal UI theme
/permission	Select permission mode
/grants	Review and revoke session approvals
/editor	Set external editor
/settings	Open TUI settings
/init	Analyze codebase and generate AGENTS.md
/update	Update Scream Code
/version	Show version info
Extensions
/mcp	Manage MCP servers
/plugin (/skills, /plugin)	Skill center
/extension	Code extensions: activate or deactivate a plugin entry point
/make-skill	Distill the session into a Skill
/image	Draw or edit an image (image skill; set up once with /config image)
/line	Native IM channels: Feishu/Lark & WeChat (wizard + daemon)
Tools
/search	Search the conversation (Esc to close)
/trace	View the session working trajectory
/hl (/highlight)	Toggle user-message highlight block
/blockrows	Adjust activity block rows (collapsed height, tool-result rows, reasoning rows)
/codebg	Toggle the background panel behind code blocks
/mermaid	Choose how ```mermaid blocks render: drawn with box-drawing frames · the same drawing framed in ASCII (for terminals that render box glyphs two cells wide) · left as source
/snaptimer (/timer)	Toggle per-turn elapsed timer
/sidebar	Open/close the sidebar panel (Ctrl+X)
/tasks (/task)	Browse background tasks
/cron	View and manage scheduled tasks — list, create (pick a time + a task), delete
/like	Set your preferences
/help (/h)	Show commands and shortcuts
/hotkeys (/keys)	Keyboard shortcut reference
/copy (/yank)	Copy the last reply to the clipboard
/exit (/quit, /q)	Exit application

Shortcuts: Ctrl+S interrupt · Ctrl+C cancel · Ctrl+O expand tool output · Ctrl+Shift+F search · Shift+Tab plan mode · Shift+Enter new line · Tab (empty) cycle thinking effort · @ mention a file

Documentation

Website: scream.chat

• Configuration — providers, model aliases and image generation: docs/configuration.md
• Skills — skill packages, discovery and /skill:<name>: docs/skills.md
• MCP — external tool servers: docs/mcp.md
• Sessions — storage, resume, fork and export: docs/sessions.md
• Feishu & WeChat channels — the /line wizard and daemon: docs/line.md
• Architecture — package layout and prompt assembly: docs/architecture.md
• Self-Evolution manual — walk through making, installing, tripping, and rolling back a plugin: packages/agent-core/docs/self-evolution-e2e.md.

Contributing

Free and open — forks, feedback and pull requests are welcome. Scream is a lightweight agent foundation: maximize the model's own capability, don't over-constrain it with framework. Inspired by the wider agent-tooling community.

---

GitHub · scream.chat · MIT License · Made with ❤️ by LIUTod