Sidekick/README.md

# Sidekick

Sidekick is a production-ready agentic framework written in Go 1.25. It provides a robust architecture for building AI assistants with hierarchical orchestration, native Model Context Protocol (MCP) integration, and a rich terminal user interface (TUI).

## Features

*   **Hierarchical Orchestration:** Support for complex agent topologies, including coordinators and specialized subagents.
*   **Model Context Protocol (MCP):** Native integration for calling external tools via MCP, supporting `stdio`, `sse`, and `http` transports (via `mark3labs/mcp-go`).
*   **Intelligent Buffering:** Automatically buffers large tool outputs to prevent context window exhaustion, returning file pointers for significant payloads.
*   **Rich Terminal UI:** A beautiful, responsive TUI built with Charmbracelet's BubbleTea and Lipgloss, featuring status bars, role-based formatting, and dynamic viewports.
*   **Advanced Prompt Templating:** Define complex, multi-line system prompts using TOML. Support for Go's `text/template` engine allows you to compose modular prompts from reusable snippets.
*   **Configuration Driven:** Easily configure models, agents, tools, and MCP servers via a declarative `config.toml` file.

## Installation

### Prerequisites

*   Go 1.25 or higher.

### Installing the Library

To use Sidekick as a framework in your own Go projects:

```bash
go get github.com/yourusername/sidekick-ng
```

### Installing the TUI

To install the Sidekick TUI binary globally:

```bash
go install github.com/yourusername/sidekick-ng/cmd/sidekick-tui@latest
```

Alternatively, you can build it locally from the source:

```bash
git clone https://github.com/yourusername/sidekick-ng.git
cd sidekick-ng
go build -o bin/sidekick-tui ./cmd/sidekick-tui
```

## Configuration

Sidekick relies on two primary configuration files: `config.toml` for system settings and `prompts.toml` for advanced system prompt management.

**Important:** When running the TUI, the binary expects `config.toml` and `prompts.toml` to be present in the directory from which the command is executed.
### `config.toml`

This file defines your models, MCP servers, and agent profiles.

```toml
tool_response_threshold = 10000 # Bytes after which tool results are buffered to files

[models.default]
```

model_id = "env:DEFAULT_MODEL_ID"
endpoint = "env:DEFAULT_MODEL_ENDPOINT"
api_key = "env:DEFAULT_MODEL_API_KEY"
temperature = 0.0
max_tokens = 4096

[mcp_servers.filesystem]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

[agents.coordinator]
role = "COORDINATOR"
model_id = "default"
system_prompt = "You are the primary coordinator agent." # This can be overridden by prompts.toml
subagents = ["researcher"]
toolsets = ["filesystem"]
```

### `prompts.toml`

Use this file to define complex, multi-line system prompts. If an entry here matches an agent's ID in `config.toml`, it will override the inline `system_prompt`. It uses Go's `text/template` engine, allowing you to compose prompts dynamically.

```toml
base_identity = """
You are a highly capable agentic assistant built on the Sidekick framework.
Always be professional, concise, and helpful.
"""

coordinator = """
{{template "base_identity"}}

You are the COORDINATOR agent. Your primary responsibility is to understand the 
user's request and delegate tasks accordingly.
"""
```

## Usage

### Running the TUI

1.  Ensure you have `config.toml` (and optionally `prompts.toml`) in your current directory.
2.  Set any necessary environment variables defined in your config (e.g., `DEFAULT_MODEL_API_KEY`).
3.  Run the TUI:

```bash
./bin/sidekick-tui
```

*   **Input:** Type your messages at the bottom prompt.
*   **Send:** Press `Enter` to send a message.
*   **Quit:** Press `ctrl+c` to exit.
*   **Scrolling:** Use the mouse wheel or arrow keys to scroll through the conversation history.

### Using the Framework Programmatically

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/yourusername/sidekick-ng"
)

func main() {
	// 1. Load Configuration
	cfg, err := sidekick.LoadConfig("config.toml")
	if err != nil {
		log.Fatal(err)
	}

	// 2. Load and Apply Prompts (Optional)
	tmpl, _ := sidekick.LoadPrompts("prompts.toml")

	// 3. Initialize Agent
	agentCfg := cfg.Agents["coordinator"]
	
	// Apply template override if exists
	if tmpl != nil && tmpl.Lookup("coordinator") != nil {
		if rendered, err := sidekick.RenderPrompt(tmpl, "coordinator"); err == nil {
			agentCfg.SystemPrompt = rendered
		}
	}

	agent := sidekick.NewAgent("coordinator", agentCfg, cfg)

	// 4. Run the Agent Loop
	ctx := context.Background()
	result, err := agent.Run(ctx, "What files are in the /tmp directory?")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}
```

## Contributing

Contributions are welcome! Please ensure that all code adheres to the project's strict coding standards defined in `AGENTS.md` (e.g., 2-space indentation, max 112 characters per line, double-quoted strings).

## License

MIT