Sunshine

Sunshine is a terminal coding agent for working inside real repositories. It can inspect code, edit files, run commands, review changes, and keep project-scoped conversation history so you can pick work back up without rebuilding context.

Built with Mastra and pi-tui.

What the agent can do

• Read and search your workspace, including fuzzy file lookup with @ references
• Edit code and other project files directly from the chat
• Run shell commands in your workspace and stream output back into the conversation
• Switch between models and providers depending on the task
• Use MCP servers, hooks, and custom slash commands as part of the workflow
• Review diffs and GitHub pull requests
• Store project-scoped threads, token usage, and approved plans so context persists over time
• Load custom modes, subagents, and skills from user or project directories

Features

• Repository-aware conversations: Threads are scoped to the current project and resume automatically
• Tool-using agent: File reads, edits, search, and command execution are built in
• Model flexibility: Use Anthropic, OpenAI, Gemini, and other providers through Mastra's model router
• Approval controls: Require confirmation for tool calls or switch to YOLO mode for faster iteration
• Extensible runtime: Add custom agents, MCP servers, hooks, and OpenAI-compatible providers
• Persistent memory and usage tracking: Keep token counts, plans, and long-running context available across sessions
• Terminal-native UI: Streaming output, diff views, slash commands, and keyboard shortcuts tuned for coding work

Installation

Sunshine requires Node.js >=22.13.0.

Install globally:

npm install -g @ngandu/sunshine

Or run it without a global install:

npx @ngandu/sunshine

The npm package includes TypeScript and the TypeScript language server for JavaScript and TypeScript workspace support. If your repository already has its own TypeScript toolchain, Sunshine prefers the workspace-local SDK and language server.

Start the agent with:

sunshine

First run

On first launch, Sunshine walks you through:

1. Authentication with your preferred provider
2. Default model pack selection for the available agent modes
3. Observational Memory model selection
4. Tool approval behavior, including optional YOLO mode

You can run the setup flow again anytime with /setup.

Usage

Talk to the agent

Type a request and press Enter. If the agent is already working, Enter queues your next message and sends it after the current run finishes.

Typical requests:

• Find where auth tokens are stored and explain the flow
• Refactor the session manager to reduce duplication
• Run the tests for the HTTP layer and fix failures
• Review the current diff for regressions
• Wire this MCP server into the current workspace

Reference files with @

Type @ followed by part of a filename to fuzzy-search project files and attach them to your prompt.

• @setup matches files like setup.ts or setup.py
• @src/tui scopes suggestions to a directory
• @"path with spaces" supports quoted paths

Select a suggestion with the arrow keys and press Tab to insert it.

Optional: install fd for @ autocomplete

The @ autocomplete feature uses fd, which respects .gitignore. Without it, @ autocomplete silently does nothing.

# macOS
brew install fd

# Ubuntu/Debian
sudo apt install fd-find

# Arch
sudo pacman -S fd

On Ubuntu/Debian the binary is called fdfind. Sunshine detects both fd and fdfind automatically.

Slash commands

| Command | Description | | --- | --- | | /new | Start a new conversation thread | | /clone | Clone the current thread | | /threads | List and switch between threads | | /name | Rename the current thread | | /resource | Show or switch the current resource ID | | /thread:tag-dir | Tag the current thread with a directory | | /mode | Switch the active agent mode | | /models | Choose or manage model packs | | /subagents | Configure default models for subagents | | /om | Configure Observational Memory models | | /think | Set Anthropic thinking level | | /skills | List available skills | | /custom-providers | Manage OpenAI-compatible providers and models | | /login | Authenticate with OAuth or save a named API key | | /logout | Log out from a provider | | /permissions | View or manage tool approval permissions | | /yolo | Toggle auto-approval for all tools | | /sandbox | Manage allowed workspace paths | | /hooks | Show or reload configured hooks | | /mcp | Show or reload MCP server connections | | /diff | Show modified files or git diff | | /review | Review a GitHub pull request | | /report-issue | Report an issue from inside the TUI | | /cost | Show token usage and estimated cost | | /settings | Open general settings | | /theme | Switch the TUI theme | | /update | Check for updates | | /setup | Re-run the onboarding flow | | /help | Show available commands | | /exit | Exit the TUI |

Keyboard shortcuts

| Shortcut | Action | | --- | --- | | Enter | Send a message, or queue a follow-up while the agent is running | | Ctrl+C | Interrupt the current operation or clear input | | Ctrl+C Ctrl+C | Exit | | Ctrl+D | Exit when the editor is empty | | Ctrl+Z | Suspend the process | | Alt+Z | Undo the last clear | | Ctrl+T | Toggle thinking block visibility | | Ctrl+E | Expand or collapse all tool outputs | | Ctrl+Y | Toggle YOLO mode |

Configuration

Project-scoped threads

Threads are associated with a project using:

1. Git remote URL, when available
2. Absolute path as a fallback

That lets conversations follow the same repository across clones, worktrees, and SSH or HTTPS remotes.

Data location

Sunshine stores its SQLite database and related state in your application data directory:

• macOS: ~/Library/Application Support/sunshine/
• Linux: ~/.local/share/sunshine/
• Windows: %APPDATA%/sunshine/

Credentials saved with /login are stored alongside the database in auth.json. Custom provider configuration is stored in settings.json.

Authentication

For Anthropic, Sunshine supports:

1. Claude Max OAuth through /login
2. Direct API key through /login or ANTHROPIC_API_KEY

When both are available, Claude Max OAuth takes priority.

For OpenAI, use /login to authenticate with OAuth or save a named API key. For Google, use /login to save a Gemini API key or set GOOGLE_GENERATIVE_AI_API_KEY. Other providers can be configured through their environment variables or through /custom-providers if they expose an OpenAI-compatible API.

Custom providers

Use /custom-providers to add OpenAI-compatible providers with:

• a provider name
• a provider url
• an optional provider apiKey
• one or more custom model IDs

Once saved, those models appear in selectors such as /models and /subagents.

If you store an API key in settings, it is saved locally in plaintext. Use that only on a machine and user profile you trust.

Custom agents

Modes and subagents are defined as markdown files named <name>.agent.md.

Sunshine loads built-in agent files from the package and also discovers custom agent files in directories such as:

• .sunshine/agents/
• .claude/agents/
• .ulicode/agents/
• .mastracode/agents/

Project agent files override user files, and user files override built-ins when they share the same kind and id.

Example mode definition:

---
id: ask
kind: mode
name: Ask
defaultModelId: openai/gpt-5.3-codex
subagents:
    - explore
---
# Ask Mode

Use this mode for investigation, explanation, and light edits.

Example subagent definition:

---
id: explore
kind: subagent
name: Explore
defaultModelFromMode: ask
tools:
    - task_check
allowedBuiltInTools:
    - subagent
allowedSubagents:
    - audit-tests
allowedWorkspaceTools:
    - view
    - find_files
    - search_content
---
Explore the codebase and report findings without editing files.

allowedBuiltInTools: [subagent] lets a subagent fan out work to more subagents. Use it sparingly and keep parent agents responsible for synthesis and verification.

When delegating to a subagent at runtime, prefer the structured brief payload over a free-form task string. For write-capable child work, include brief.writeScope so parallel edit conflicts can be rejected automatically.

Supported metadata keys include:

• id, kind, name, description
• defaultModelId, default, color, subagents for modes
• defaultModelFromMode, tools, allowedHarnessTools, allowedBuiltInTools, allowedSubagents, allowedWorkspaceTools for subagents

Plan persistence

Approved plans are saved as markdown files under the app data directory:

• macOS: ~/Library/Application Support/sunshine/plans/<resourceId>/
• Linux: ~/.local/share/sunshine/plans/<resourceId>/
• Windows: %APPDATA%/sunshine/plans/<resourceId>/

To store plans inside the project instead, set:

export SUNSHINE_PLANS_DIR=.sunshine/plans

Credits

• Mastra for the agent framework
• pi-mono for terminal UI primitives and inspiration
• OpenCode for OAuth provider patterns

License

Apache-2.0