current state

README.md

@@ -0,0 +1,165 @@
+# 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