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:

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

go get codeberg.org/luxferre/Sidekick

Installing the TUI

To install the Sidekick TUI binary globally:

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

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

make

Or manually:

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.

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

• Input: Type your messages at the bottom prompt.
• Markdown: Agent responses are rendered as formatted Markdown.
• Send: Press Enter to send a message.
• Newline: Press Ctrl+J to insert a newline in your message.
• Scrolling:
  • Use Ctrl+U or PgUp to scroll up.
  • Use Ctrl+D or 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:

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

Using the Framework Programmatically

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.