STUDY Agent

clean-agent-standalone is a clean-room, terminal-first AI agent project that rebuilds a modern agent runtime without copying proprietary source code.

It is designed as an independent TypeScript project with:

• a conversational terminal UX
• session persistence and replay
• tool execution and delegation
• team/coordinator workflows
• skills, profiles, and output styles
• runtime diagnostics, snapshots, and recovery
• an experience-transfer foundation for cross-task generalization

What This Project Is

This project is not just a toy REPL.

It is a standalone runtime that tries to capture the useful architecture of a full agent system:

• agent loop
• tool orchestration
• sub-agent delegation
• session recovery
• team task coordination
• skill loading
• structured runtime services
• observable terminal UX

The implementation is clean-room and intentionally independent from the source repository being studied.

Current Highlights

• Terminal chat UX with welcome screen, input box, and lightweight conversation styling
• Animated terminal waiting state with a stick-figure runner
• Session persistence under .clean-agent/sessions
• Resume by latest session or explicit session id
• Full transcript preview on resume
• Session search, inspect, clone, and replay flows
• Runtime snapshots under .clean-agent/snapshots
• Runtime log and doctor diagnostics
• Heuristic local model for offline use
• OpenAI-compatible model adapter for real providers
• Built-in tools for shell, files, search, delegation, tasks, and web fetch/search
• Team and coordinator mode with mailbox and task board
• Skills, agent profiles, and output styles loaded from local directories
• Experience transfer / repair framework already wired into the runtime

For the full implemented surface area, see:

• IMPLEMENTED_FEATURES.md

Quick Start

cd /home/ubuntu/dev/clean-agent-standalone
npm install
npm run build
npm start

Run With A Real Model

Use an OpenAI-compatible provider:

CLEAN_AGENT_MODEL="openai" \
OPENAI_API_KEY="your_key" \
OPENAI_BASE_URL="https://api.deepseek.com" \
OPENAI_MODEL="deepseek-chat" \
npm start

Resume A Conversation

Resume the latest session:

npm start -- --resume-latest

Resume a specific session:

npm start -- --resume <session-id>

Equivalent legacy form:

npm start -- --session <session-id>

Example with a real model:

CLEAN_AGENT_MODEL="openai" \
OPENAI_API_KEY="your_key" \
OPENAI_BASE_URL="https://api.deepseek.com" \
OPENAI_MODEL="deepseek-chat" \
npm start -- --resume <session-id>

Skills And Generalization

The project already has a real skills layer, not just a placeholder.

Current skill capabilities:

• load skills dynamically from .clean-agent/skills
• support skill.json
• support skill.md / *.skill.md with YAML frontmatter
• support include composition
• support parameters substitution
• allow skills to register tools
• allow skills to register slash commands

Why this matters for generalization:

• skills are not hardcoded into one specific task
• the same skill package can be reused across different sessions and goals
• skill instructions can be parameterized instead of duplicated
• loaded skills plug into the same runtime used by the main agent, delegated agents, and team flows

This means the project already supports reusable task capability packs, even though stronger automatic skill selection and deeper experience-guided orchestration are still being improved.

Main Runtime Capabilities

Agent Runtime

• multi-step agent loop
• tool call execution
• permission gate
• context compression
• token/cost tracking
• delegated agent support

Session And Recovery

• save sessions
• inspect sessions
• preview sessions
• search sessions
• clone sessions
• replay sessions
• bridge export/import/restore

Tools

Built-in tool families include:

• shell tools
• file tools
• search tools
• task tools
• delegation tools
• session export tools
• web fetch/search tools

Team / Coordinator

• team creation and member registration
• task board
• task dispatch and claiming
• worker completion reporting
• coordinator planning and assignment
• proactive scan loop

Runtime Observability

• runtime snapshots
• runtime logs
• environment/version inspection
• conversation summary
• doctor diagnostics
• worktree inspection

Important CLI Commands

Session

• /sessions
• /resume
• /resume inspect <session-id>
• /resume preview <session-id> [limit]
• /session-info [session-id]
• /session-search <query>
• /replay clone <session-id> [target]
• /replay run <session-id> <prompt>

Runtime

• /doctor
• /logs
• /logs tail [count]
• /env
• /version
• /summary
• /services

Snapshots

• /persist [name]
• /snapshots
• /snapshots show <name>

Tools / Planning

• /tool-search
• /decompose <goal>
• /compact
• /cost

Governance / Settings

• /provider
• /permissions
• /hooks-control
• /settings
• /flags

Skills / Profiles / Styles

• /skills
• /skills-search
• /agents
• /output-style

Team / Coordination

• /team
• /team-member
• /team-tasks
• /team-add-task
• /team-claim
• /team-complete
• /team-inbox
• /team-message
• /coordinator
• /proactive

Tasks

• /tasks
• /task <id>
• /stop-task <id>
• /task-runs
• /task-run <prompt>

MCP

• /mcp-connect <name> <command> [args...]
• /mcp-disconnect <name>
• /mcp-list

Project Layout

Key directories:

• src/agent: agent loop, sessions, permissions, tool execution
• src/skills: dynamic skill loading and catalog
• src/experience: transfer, repair, and write-back logic
• src/team: team manager, mailbox, task board
• src/tools: built-in tool definitions
• src/services: runtime services and diagnostics
• src/tasks: local task runner and task framework
• src/bridge: session bridge import/export/restore
• src/model: heuristic and OpenAI-compatible model clients
• src/utils: snapshots, shell info, release info, summaries, worktree helpers

Runtime Data Directories

At runtime, local state is stored under:

• .clean-agent/settings.json
• .clean-agent/sessions/
• .clean-agent/snapshots/
• .clean-agent/runtime.log
• .clean-agent/tasks/
• .clean-agent/skills/
• .clean-agent/agents/
• .clean-agent/output-styles/

Current Boundaries

The project is already substantial, but there are still boundaries:

• heuristic mode is still limited compared with a real model
• skill generalization is real, but stronger automatic skill selection can be improved
• experience transfer is wired in, but the write-back and matching quality can still be deepened
• terminal UX is intentionally lightweight, not a full graphical interface
• background service behavior is still simpler than a full daemonized production runtime

Related Docs

• IMPLEMENTED_FEATURES.md

study-agent