166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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
|