From prompt
to action.

You need a terminal, Node.js, and an API key for your chosen AI model provider. Add optional services (Docker, Telegram, search) only when you need them.

How Sun2Agent works

Sun2Agent operates as a lightweight, 100% local ReAct (Reasoning + Acting) agent harness directly inside your terminal. It connects your local workspace context and tools to any OpenAI-compatible LLM endpoint using standard Chat Completions function calling. The agent evaluates goals, requests tools, runs them on your machine with 5-layer guardrails and Human-in-the-Loop approval, and feeds results back until your task is finished.

Prerequisites

• Node.js 20 or 22+ and npm. Verify with node --version.
• A model API key: built-in NVIDIA NIM, or an API key and base URL for any OpenAI-compatible provider (OpenAI, Groq, OpenRouter, local Ollama).
• Internet access for installing packages and communicating with your model provider endpoint.

Sun2Agent runs natively on macOS, Linux, and Windows. Choose the installation method that fits your workflow.

How workspace execution works

Sun2Agent binds its filesystem tools and execution context strictly to the folder from which you launch it. That directory becomes your active workspace root: file reads, edits, and tests are restricted inside it, preventing unintended modifications to other parts of your computer.

1. Install globally (recommended for everyday use)

Install Sun2Agent globally so the sun2agent command is instantly available in any terminal window or project folder:

npm install -g sun2agent
cd /path/to/your/project
sun2agent

To update an existing global installation to the latest version at any time, run npm install -g sun2agent@latest.

2. Or try immediately with npx (zero installation)

If you prefer to try Sun2Agent immediately without installing anything globally on your machine, launch it in any project folder using npx:

cd /path/to/your/project
npx sun2agent

3. Developer install guide (run from source & contribute)

For contributors, hackers, or developers who want to modify the source code, run tests, or build custom integrations:

git clone https://github.com/snowhypers/Sun2Agent.git
cd Sun2Agent
npm install
npm test
npm start

To link your local development build globally across your system so typing sun2agent executes your cloned repository code, run npm link inside the cloned directory.

On your first launch, Sun2Agent guides you through an interactive setup menu to connect your model and preferences.

How configuration works

All configuration is stored locally in ~/.sun2agent/config.json with owner-only file permissions (0600). Credentials are kept on your machine and never synced to external servers or telemetry services. You can re-open configuration at any time by typing /config.

How to configure

1. Provider and model: Select built-in NVIDIA NIM or add a custom OpenAI-compatible provider (e.g., OpenAI, Groq, OpenRouter, or local Ollama).
2. API key: Paste your provider API key into the secure, hidden input. When updating later, press Enter to keep your saved key.
3. Model ID: Pick a listed model or type the exact model identifier supported by your endpoint (e.g., meta/llama-3.3-70b-instruct, gpt-4o, llama3.2).
4. Optional services: Separately toggle Tavily web search, persistent memory, LangSmith tracing, or Telegram integration.
5. Done: Select Done to save changes and enter the interactive terminal agent loop.

› Explain this project's structure and suggest the first test to run.

File tools are available automatically. There is no setup command needed: launch Sun2Agent from your project folder and describe your goal in natural language.

How workspace tools work

• Autonomous file management: The agent automatically calls read_file, write_file, replace_file_content, and list_dir to inspect code and apply targeted edits.
• Path sandboxing & security: File access is strictly locked to your workspace root directory. filesystemGuard blocks directory traversal attacks and prevents reading sensitive files like .env or SSH private keys.
• Human-in-the-Loop policy: Read-only operations run automatically. File creations and edits request approval for routine modifications per prompt; destructive deletions always require explicit fresh confirmation.

How Maven test verification works

For Java codebases, Sun2Agent provides an automated test-verification cycle:

1. Authoring tests: Ask the agent to generate JUnit or TestNG tests under src/test/java.
2. Fresh approval execution: The agent requests human approval to execute mvn test within your workspace.
3. Autonomous diagnosis: If assertions fail or compilation errors arise, the agent inspects the failure stack trace, applies code fixes, and asks for approval to re-test.
4. Verification report: Unverified work or failing assertions are clearly reported until the build passes cleanly.

Project conventions with AGENT.md

Store project conventions, lint rules, and architectural guidelines in an AGENT.md file at your workspace root. Type /agent in chat to view or create it.

AGENT.md provides repository-specific guidelines, architectural rules, coding conventions, and test requirements that Sun2Agent automatically follows whenever operating in your codebase.

How AGENT.md works

• Workspace scoping: Sun2Agent automatically searches for AGENT.md in the directory from which you launch it. Each repository maintains its own isolated rules.
• System prompt injection: Instructions from AGENT.md are injected into the model's system prompt under Repository Instructions (from AGENT.md) on every turn.
• Cached with instant reload: Rules are cached in memory for zero-latency execution. Running /agent reloads the file from disk immediately so edits take effect on the very next turn.
• Safety priority: Instructions in AGENT.md are advisory; they enforce team conventions and style guides, but cannot bypass 5-layer guardrails, override approvals, or breach Docker boundaries.

Example AGENT.md template

# Project Guidelines

## Tech Stack & Standards
- Node.js 22, ESM modules, strict TypeScript
- Formatting: 2 spaces, single quotes, no semicolons

## Testing & Verification
- Run tests via `npm test` after modifying any file in src/
- Always verify all assertions pass before reporting completion

## Workflows & Git
- Do not commit directly to `main`
- Keep changes minimal and focused strictly on the requested task

How to use AGENT.md

1. Type /agent in the Sun2Agent prompt to open ./AGENT.md in your editor.
2. Add or modify conventions, style guidelines, and build commands.
3. Save and close the file, then press Enter in the terminal. Sun2Agent confirms: ✔ AGENT.md reloaded. Its instructions are now active.

Manage active conversation context, restore interrupted workflows, and save persistent preferences locally.

How session and memory management works

How the /save command works

While Sun2Agent automatically checkpoints raw session state to allow /continue resumption, the /save command lets you summarize and persist intentional workspace memories.

• Automatic multi-turn summary: Analyzes recent conversation turns and drafts a structured summary detailing your goal, key technical decisions, and modified files.
• Zero secret leakage: Summaries pass through guardrails.sanitizeOutput to guarantee no API keys, tokens, or private credentials are saved.
• Workspace scoping: Memories are stored in ~/.sun2agent/saved-sessions.json keyed specifically to your project's directory path.
• Human confirmation: Displays the draft summary and requires confirmation (Save this session memory?) before writing to disk.

Which conversations you should save to memory

Not every trivial prompt needs to be saved. Use /save for high-value conversations that will help the agent understand the project in future sessions:

• 1. Complex debugging breakthroughs: When you spend multiple turns diagnosing an obscure bug, race condition, or subtle dependency conflict, run /save so the agent remembers the root cause and why specific fixes were made.
• 2. Architectural & schema milestones: After completing a major feature slice—such as designing a new database schema, establishing an API contract, or refactoring an authentication flow—run /save so the agent retains the design rationale.
• 3. Project convention decisions: When you and the agent agree on specific coding conventions, tool preferences, or library choices that are not yet codified in AGENT.md, run /save to persist that context.
• 4. End-of-session checkpoints: Before exiting the terminal at the end of a work session, run /save to record current task progress so the next session can resume with full context.

How to use sessions & memory

• Resume an interrupted turn: Type /continue to pick up directly from the last snapshot without re-prompting.
• Start fresh: Type /new to wipe chat history and reset token retention.
• Edit your developer preferences: Type /memory to open and edit ~/.sun2agent/memory.md (e.g. "prefer functional style", "use pytest").
• Save session highlights: Type /save to review and approve an exportable task summary.

Skills are reusable instruction blocks—such as code review checklists, test templates, and framework guidelines—that you can attach to any conversation on demand.

How Skills work

• Central definition: Saved in ~/.sun2agent/skills.md. Each skill is formatted with a markdown heading and actionable instructions.
• Dynamic prompt injection: When a skill is selected, Sun2Agent injects its guidelines into the model's system prompt for that turn, ensuring adherence to your checklist.
• Visual indicator: Active skills display in brackets directly above the prompt input (e.g. [Skill: Code Review]).
• Quick dismiss: Pressing Esc on an empty input line instantly clears all active skills for the current prompt.

How to use Skills

1. Type /skills to view and toggle available skills or edit skills.md.
2. Select one or more skills from your list to activate them for your next task.
3. Type your request naturally—the model automatically follows the active skill instructions.
4. Press Esc on an empty input box anytime to clear active skills.

When an action encounters an error, a Java test fails, or a desktop outcome is left unverified, Sun2Agent analyzes what went wrong and proposes an advisory operational lesson.

How self-improvement works

• Failure detection: Identifies tool errors, failed test assertions, or unverified desktop outcomes after a turn.
• User consent required: Prompts you with Discard as the default choice. Nothing is saved without explicit approval.
• Strict local storage: Approved lessons are saved in ~/.sun2agent/lessons.json with 0600 file permissions and zero external telemetry.
• Safety & secret screening: Every lesson passes through inputGuard, outputGuard, and secret redaction to ensure no credentials or prompt injections are stored.
• Keyword-relevant retrieval: Future tasks with matching keywords load up to one relevant lesson into the context prompt to prevent recurring mistakes.

Session Memory (/save) vs. Self-Improvement (lessons.json)

Sun2Agent uses two complementary local learning mechanisms that serve distinct purposes:

• Session Memory (/save) captures what went right: Preserves features built, architectural choices, and project milestones keyed to the current workspace.
• Self-Improvement (lessons.json) captures what went wrong: Triggers after failed tool executions, broken builds, or unverified desktop actions, proposing defensive operational habits so the agent never repeats past mistakes.

Both systems are 100% local, require explicit user approval (defaulting to Discard / No), and include secret redaction.

How to use it

When a lesson is suggested after a failed action, choose Keep to save it or Discard to skip. Approved lessons apply automatically to future relevant prompts.

Live web search gives the agent access to real-time facts, documentation, and release notes without manual browsing.

How web search works

• Tavily search API: Queries the live web for authoritative developer documentation and facts when tool calling is needed.
• Indirect prompt injection defense: Web result snippets are wrapped inside strict <<<UNTRUSTED_WEB_DATA>>> boundary delimiters.
• Input guardrail screening: Every search snippet passes through guardrails.inputGuard before entering the model context, blocking hidden instructions or jailbreak attempts.
• Zero authority over workspace: Untrusted web content cannot override your project instructions (AGENT.md), bypass guardrails, or approve actions.

How to use it

1. In Sun2Agent, type /config and select Web Search.
2. Enable Tavily and paste your API key. Select Done.
3. Ask current-events or documentation questions naturally in your chat.

Automate isolated web navigation, documentation scraping, and web application testing using Playwright.

/browser
› Open nodejs.org and show me the latest release notes.

How browser automation works

• Isolated Chrome profile: Spawns a dedicated Playwright Chromium browser session on demand. Disconnected by default to save resources.
• Profile separation: Runs independently of your personal browser data and cookies; you stay protected from credential exposure.
• Human-in-the-Loop protection: Navigating and viewing pages proceed automatically; clicking, typing, submitting forms, and key presses request confirmation.

How to use it

1. Type /browser in the prompt to launch and connect the isolated browser.
2. Give instructions in plain English (e.g. “Navigate to example.com and extract header links”).
3. Press Esc on an empty input or type /browser disconnect to close the browser session.

Control your native desktop environment—inspect application windows, click UI elements, send keystrokes, and automate desktop workflows.

How computer control works

• Native OS automation: Dispatches mouse and keyboard events and inspects active windows using host accessibility APIs on macOS, Linux, and Windows.
• Fine-grained approval: Inspecting window titles and application state is read-only. Activating an app shares one approval per prompt; clicks, typing, and system scripts require explicit individual approval.
• Host isolation guard: Computer control operates on your host desktop and is intentionally disabled inside Docker sandbox containers to prevent host-escape vectors.

How to use it

1. Type /computer and confirm desktop access.
2. Choose image support if your configured model supports vision/multimodal input.
3. Review the permission report. On macOS, grant Accessibility and Screen Recording permissions in System Settings if prompted.
4. Prompt the agent with a focused desktop task, for example: “Open VS Code and bring the project window to the front.”
5. Press Esc or type /computer disconnect anytime to release desktop control.

Extend Sun2Agent with any tool ecosystem using the Model Context Protocol (MCP)—from databases to developer tools.

How MCP integration works

• Multi-transport support: Natively connects to local processes via stdio, remote servers over http (Streamable HTTP), and sse (Server-Sent Events).
• Dynamic schema discovery: Automatically discovers tool schemas and arguments, exposing them as function calls to your active LLM.
• Security boundaries: Dangerous commands or unknown tools always trigger Human-in-the-Loop confirmations before execution.

How to use it

Use /mcp in chat to manage servers interactively, or configure them directly in ~/.sun2agent/mcp.json:

{
  "mcpServers": {
    "research": {
      "type": "http",
      "url": "https://your-server.example.com/mcp",
      "telegramTools": ["search"]
    }
  }
}

The optional telegramTools property allowlists specific remote read-only tools for Telegram. Local MCP servers, browser automation, and computer control tools are never exposed over Telegram.

Connect your running Sun2Agent terminal to a private Telegram bot to query projects, execute research, and receive updates on mobile or desktop.

How Telegram integration works

• Direct long-polling: Sun2Agent connects directly to the Telegram Bot API from your machine. No webhooks or public ports needed.
• Strict user authorization: Every incoming message is checked against your configured numeric Telegram user ID. Unrecognized messages are silently ignored.
• Live streaming replies: Message text updates dynamically as the LLM generates tokens.
• Host security restrictions: Local filesystem tools, browser automation, and host desktop control are restricted from Telegram execution for safety.

How to use it

1. In Telegram, open @BotFather, send /newbot, choose a name and username, and copy your bot token.
2. Open your newly created bot and send /start.
3. Find your numeric Telegram user ID (inspect your bot’s getUpdates response or use an ID bot).
4. In Sun2Agent, run /config → Telegram, answer Yes to Connect Telegram?, and paste your bot token and chat ID. Select Done.
5. Keep Sun2Agent running in your terminal and message your bot anytime.

Automate recurring background research, system checks, and reminders delivered directly to your Telegram chat.

› Every day at 9 PM, summarize today's AI news and send it to Telegram.

› Remind me in 30 minutes to run the production test suite.

How scheduled tasks work

• Natural language schedule parsing: Automatically detects intent, interval (daily, recurring, or one-time), and execution time aligned with your local machine's timezone.
• Unattended background execution: Runs read-only queries in the background and delivers results directly to your authorized Telegram chat.
• CLI dependency: Scheduled tasks require the Sun2Agent terminal process to remain running on your machine.

How to use it

Specify three details in your prompt: what to do, when, and once or daily. Type /schedule anytime in chat to inspect, pause, or remove scheduled jobs.

Every tool call passes through five synchronized security guard layers before execution—sub-millisecond regex validation with zero extra LLM overhead.

How the 5-layer guardrails work

How Human-in-the-Loop approvals work

• Read-only checks: Listing files, reading code, and inspecting windows proceed immediately without prompting.
• Routine modifications: File edits and writes share a single approval decision for that MCP server and prompt.
• High-risk actions: Deletions, shell commands, and external messages always require a fresh, explicit decision.

How to use approvals

When an action requires confirmation, Sun2Agent displays the server name, tool, arguments, and risk level. Type y to approve or n to decline.

Run the entire agent runtime inside an isolated Docker container to protect your host system during untrusted code execution.

sun2agent sandbox enable
sun2agent sandbox status
sun2agent sandbox disable

How the Docker sandbox works

• Containerized runtime: Mounts your project directory into an isolated container. The agent cannot modify files outside the mounted project.
• Automatic session resume: If Docker restarts mid-session, Sun2Agent pauses and resumes automatically without loss of context.
• Desktop isolation: Host desktop control (/computer) is intentionally disabled inside Docker to maintain strict isolation boundaries.

How to use it

Ensure Docker Desktop or daemon is running, then run sun2agent sandbox enable before starting your session.

Track LLM calls, tool execution times, latency, token consumption, and errors with production-grade observability via LangSmith—with privacy guardrails baked in.

How LangSmith observability works

• Zero telemetry by default: Sun2Agent sends zero data to external monitoring servers unless you explicitly opt in via /config.
• Dual-layer tracing: Creates nested runs for both model API calls (traceLLM) and MCP tool executions (traceTool) using the official RunTree SDK.
• Automatic secret redaction: Prompts, completions, tool inputs, and tool outputs pass through outputGuard before dispatch to LangSmith. Bearer tokens, private keys, and API secrets are masked.
• Screenshots omitted: Binary screenshots from /browser or /computer are replaced with [Screenshot omitted from trace] placeholders to prevent data leakage.
• Non-blocking fire-and-forget: Tracing runs asynchronously in the background. Network lag or LangSmith service outages never freeze the terminal or interrupt your workflow.

How to configure and use LangSmith

1. Sign up at smith.langchain.com and generate a LangSmith API key.
2. In Sun2Agent, type /config and select LangSmith observability.
3. Choose Yes to enable tracing, then paste your LangSmith API key into the secure prompt.
4. (Optional) Specify a custom project name (defaults to sun2agent).
5. Select Done. All subsequent LLM queries and tool executions in that session will stream traces to your LangSmith project dashboard.

Quick lookup table for all built-in slash commands and keyboard shortcuts.

Keybindings & Shortcuts