npm package: @ngandu/sunshine
Description: 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.
Latest version: 0.1.8

# 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](https://mastra.ai) and [pi-tui](https://github.com/badlogic/pi-mono).

## 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:

```bash
npm install -g @ngandu/sunshine
```

Or run it without a global install:

```bash
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:

```bash
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`](https://github.com/sharkdp/fd), which respects `.gitignore`. Without it, `@` autocomplete silently does nothing.

```bash
# 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:

```md
---
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:

```md
---
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:

```bash
export SUNSHINE_PLANS_DIR=.sunshine/plans
```

## Credits

- [Mastra](https://mastra.ai) for the agent framework
- [pi-mono](https://github.com/badlogic/pi-mono) for terminal UI primitives and inspiration
- [OpenCode](https://github.com/sst/opencode) for OAuth provider patterns

## License

Apache-2.0