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:

go get github.com/yourusername/sidekick-ng

Installing the TUI

To install the Sidekick TUI binary globally:

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

Alternatively, you can build it locally from the source:

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.

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"]

[mcp_servers.remote_tools]
transport = "sse"
url = "https://api.example.com/mcp"
auth_token = "env:MCP_API_KEY" # Optional Bearer token
headers = { "X-Custom-Header" = "value" } # Optional custom headers

[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.

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:

./bin/sidekick-tui

Running the Sidekick MCP Server

Sidekick can also act as an MCP server, allowing other LLM-powered applications to leverage its agentic capabilities.

1. Configure the mcp_listener in config.toml:

[mcp_listener]
transport = "sse" # "stdio" or "sse"/"http"
port = 8080      # for sse/http

2. Run the MCP server:

./bin/sidekick-mcp

The server provides a query tool that routes requests to your coordinator agent, maintaining conversation history if provided.

• 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

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