Sidekick/README.md

# Sidekick

```
        _      __        __     _         __
  ___  (_) ___/ / ___   / /__  (_) ____  / /__
 (_-< / / / _  / / -_) /  '_/ / / / __/ /  '_/
/___//_/  \_,_/  \__/ /_/\_\ /_/  \__/ /_/\_\
----------------------------------------------
```

Sidekick is a simple but versatile 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.
*   **Internal Tools:** Built-in tools for file I/O (`read_file`, `write_file`, `grep_file`, `edit_file`) and an optional, secure `shell_exec` tool for running POSIX shell commands.
*   **Configuration Driven:** Easily configure models, agents, tools, and MCP servers via a declarative `config.toml` file.

## Internal tools

Sidekick includes a set of internal tools that are always available to agents. These tools provide common file operations and system access.

### File tools
- `read_file`: Read a file with optional line windowing.
- `write_file`: Overwrite a file with new content.
- `grep_file`: Regex search with surrounding context.
- `edit_file`: Replace a string or block of lines in a file.

### shell_exec tool

The `shell_exec` tool allows an agent to run arbitrary POSIX shell commands and receive combined stdout/stderr output. 

**Security Warning:** This tool is extremely powerful and potentially dangerous. It is **disabled by default** and must be explicitly enabled for each agent in `config.toml`.

To enable `shell_exec` for an agent, add `enable_shell_exec = true` to its configuration:

```toml
[agents.coordinator]
role = "COORDINATOR"
model_id = "default"
enable_shell_exec = true # Security: explicitly enabled
toolsets = ["filesystem"]
```

## Installation

### Prerequisites

*   Go 1.25 or higher.

### Installing the Library

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

```bash
go get codeberg.org/luxferre/Sidekick
```

### Installing the TUI

To install the Sidekick TUI binary globally:

```bash
go install codeberg.org/luxferre/Sidekick/cmd/sidekick-tui@latest
```

Alternatively, you can build it locally from the source using the provided `Makefile`:

```bash
make
```

Or manually:

```bash
git clone https://codeberg.org/luxferre/Sidekick.git
cd Sidekick
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"]

[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
streaming = false # Set to true to enable real-time token streaming
log_intermediate = false # Set to true to log intermediate reasoning and tool calls
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.
*   **Commands:** Type **`/clear`** and press `Enter` to reset the conversation history.
*   **Markdown:** Agent responses are rendered as formatted Markdown.
*   **Send:** Press `Enter` to send a message.
*   **Cancel:** Press **`Ctrl+D`** while the agent is thinking to cancel the current request.
*   **Newline:** Press `Ctrl+J` to insert a newline in your message.
*   **Scrolling:** 
    *   Use **`Ctrl+U`** or **`PgUp`** to scroll up.
    *   Use **`PgDn`** to scroll down.
    *   Mouse wheel is also supported.
*   **Quit:** Press `Ctrl+C` or `Esc` to exit.

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

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

2.  Run the MCP server:

```bash
./bin/sidekick-mcp
```

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

### Using the framework programmatically

```go
package main

import (
  "context"
  "fmt"
  "log"

  "codeberg.org/luxferre/Sidekick"
)

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)
}
```

## FAQ

### Is this related to your older Sidekick project from 2025?

Yes and no. That Sidekick had been created more as a Python exercise in creating something in the simple coding assistant field. This Sidekick can surely be used as a coding assistant too with an appropriate frontend (which is probably coming soon) but it also replaces EXAI and similar agentic initiatives of mine, because it can be used for pretty much anything you can think of.

### Why is it now written in Go?

Speed, robustness, platform support. Writing the same in C would involve a lot more work and edge case coverage.

### Will there be any other features added?

Yes, but don't think much in terms of user-facing features. Think of it as a Lego: Sidekick gives you a good set of building blocks to orchestrate the flow, it's totally up to you what to do with these blocks. That's why it also exposes itself as an MCP server: to be called by other agents. You can even configure a Sidekick subagent to call another running instance of itself if you really need to. However, because of the subagentic architecture, you most probably won't need this.

### Is Sidekick going to include a more beautiful TUI application, tailored for coder's needs (like OpenCode, Claude Code, Gemini CLI, Qwen Code etc)?

Yes, there are plans to implement something like that once the core agentic functionality is polished. It may be a totally separate application or a `sidekick-tui` evolution. The current `sidekick-tui` is more tailored for testing your agent configurations (`config.toml` and `prompt.toml`) without having to spin up the MCP server.

## Credits

Created by Luxferre in 2026, released into the public domain with no warranties.