Configuration

sharur uses layered JSON configuration. Project-level settings override global defaults.

config.json Schema

{
  "defaultModel": "llama3.2",
  "defaultProvider": "ollama",
  "theme": "dark",
  "thinkingLevel": "medium",
  "ollamaBaseURL": "http://localhost:11434",
  "openAIBaseURL": "https://api.openai.com/v1",
  "openAIApiKey": "",
  "anthropicApiKey": "",
  "anthropicApiVersion": "",
  "googleApiKey": "",
  "llamaCppBaseURL": "http://localhost:8080",
  "compaction": {
    "enabled": true,
    "reserveTokens": 2048,
    "keepRecentTokens": 8192
  }
}

API keys can also be set via environment variables — env vars take priority over config file values.

Context Files

sharur auto-discovers AGENTS.md, CLAUDE.md, GEMINI.md, and .context.md in your project root and parent directories and injects them into the system prompt. Outermost files take precedence (parent directory wins over project root).

Disable with --no-context-files.

CLI Flags

Mode

Model / Provider

Session

System Prompt

Tools

Extensions / Skills / Prompts

Output / Info

Provider Setup

sharur supports five LLM providers. All configuration lives in config.json files or environment variables; environment variables take priority over config file values.

Model Naming

Models can be specified as provider/model shorthand or with separate flags:

# Shorthand: provider inferred from the slash-prefix
shr --model anthropic/claude-sonnet-4-6

# Explicit: provider and model as separate flags
shr --provider anthropic --model claude-sonnet-4-6

Both forms are equivalent. The shorthand is convenient for one-off overrides; the config file form is better for persistent defaults.

Environment Variables

API keys set via environment variable take priority over values in config.json. The env var names use the SHARUR_ prefix:

Ollama and llama.cpp are local servers and do not use API keys.

Ollama

Ollama runs models locally. It is the default provider.

// ~/.sharur/config.json or .sharur/config.json
{
  "defaultProvider": "ollama",
  "defaultModel": "llama3.2",
  "ollamaBaseURL": "http://localhost:11434"
}

# Pull a model and launch
ollama pull llama3.2
shr

# Use a specific model
shr --model ollama/llama3.2

# Point at a remote Ollama server
shr --model llama3.2 --provider ollama

Notes:

• Default base URL is http://localhost:11434. Override with ollamaBaseURL.
• Ollama models support tools and images (vision models).
• Use shr --list-models to see all locally available models.
• Thinking is supported on models that emit <think> tokens (e.g. qwq, deepseek-r1).

llama.cpp

llama.cpp exposes an OpenAI-compatible HTTP server.

{
  "defaultProvider": "llamacpp",
  "llamaCppBaseURL": "http://localhost:8080"
}

# Start the llama.cpp server (example)
./llama-server -m model.gguf --port 8080

# Connect with sharur
shr --provider llamacpp --model my-model

Notes:

• Default base URL is http://localhost:8080. Override with llamaCppBaseURL.
• The model name passed to shr is forwarded to the server as-is.
• Image attachments are not supported.
• The server’s own context window size is used; sharur queries /v1/models to detect it.

OpenAI

{
  "defaultProvider": "openai",
  "defaultModel": "gpt-4o",
  "openAIApiKey": "",
  "openAIBaseURL": "https://api.openai.com/v1"
}

# Via environment variable (recommended)
export SHARUR_OPENAI_API_KEY=sk-...
shr --model openai/gpt-4o

# One-off key override
shr --provider openai --model gpt-4o --api-key sk-...

OpenAI-compatible endpoints:

Any server that implements the OpenAI chat completions API can be used by pointing openAIBaseURL at it:

{
  "defaultProvider": "openai",
  "openAIBaseURL": "http://localhost:11434/v1",
  "openAIApiKey": "unused"
}

This works with vLLM, LM Studio, and others.

Notes:

• Reasoning models (o3, o4-mini) emit thinking deltas that appear in the TUI and JSON event stream.
• Supports tools and vision (images) for compatible models.

Anthropic

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-6",
  "anthropicApiKey": "",
  "anthropicApiVersion": ""
}

export SHARUR_ANTHROPIC_API_KEY=sk-ant-...
shr --model anthropic/claude-sonnet-4-6

# Extended thinking (claude-3-7-sonnet and later)
shr --model anthropic/claude-3-7-sonnet-20250219 --thinking high

Notes:

• Extended thinking is supported for models that enable it (e.g. claude-3-7-sonnet). Use --thinking medium or --thinking high.
• medium thinking uses a 10,000-token budget; high uses 20,000 tokens. Temperature is automatically set to the required value.
• anthropicApiVersion overrides the anthropic-version request header; leave empty to use the library default.

Google Gemini

{
  "defaultProvider": "google",
  "defaultModel": "gemini-2.0-flash",
  "googleApiKey": ""
}

export SHARUR_GOOGLE_API_KEY=AIza...
shr --model google/gemini-2.0-flash

Notes:

• Gemini 1.5 Pro and later have a 1M+ token context window.
• Supports tools and vision (images).
• Use shr --list-models to see available Gemini models.

Listing Available Models

All five providers implement model listing. Use --list-models to query the active provider:

# List Ollama models
shr --list-models

# List models from a specific provider
shr --provider anthropic --list-models

# Filter results
shr --provider openai --list-models gpt-4

The output is a plain list of model names, suitable for piping:

shr --list-models | fzf | xargs -I{} shr --model {}

Provider Feature Matrix

TUI

The TUI is a rich, Bubble Tea-powered interface with real-time streaming, tool cards, session management, and a live context usage progress bar in the status footer.

Keybindings

Slash Commands

Session Tree Modal (/tree)

Bang Commands

Bang commands execute a shell command and inject the output into the conversation:

!ls -la          # Execute shell command, paste output into editor
!!cat README.md  # Execute shell command, send output directly to agent

• !cmd — pastes stdout into the editor so you can review before sending
• !!cmd — sends stdout directly to the agent without review

At-File Attachments

Type @ in the input to fuzzy-search and attach file contents to your prompt:

Tell me what this does @src/agent/loop.go

The file content is embedded inline in the message sent to the agent.

JSON Mode

JSON mode runs a single prompt and streams the agent’s events as line-delimited JSON (JSONL) to stdout. It is designed for shell pipelines and tooling integration.

shr --mode json "What is the best way to structure a Go project?"

# Pipe stdin as context
cat main.go | shr --mode json "Refactor this to use interfaces"

# Specify a model
shr --mode json "Summarize the last 10 git commits" --model anthropic/claude-opus-4-5

Event Format

Each line is the protobuf JSON encoding of an AgentEvent. Event types mirror the TUI stream:

• EVENT_AGENT_START / EVENT_AGENT_END
• EVENT_TEXT_DELTA — incremental response text
• EVENT_THINKING_DELTA — incremental thinking text (extended thinking models)
• EVENT_TOOL_CALL — tool invocation start
• EVENT_TOOL_DELTA — streaming tool output
• EVENT_TOOL_OUTPUT — final tool result
• EVENT_TURN_START / EVENT_TURN_END

Common Patterns

# Capture only the text deltas
shr --mode json "Explain Go interfaces" \
  | jq -r 'select(.type == "EVENT_TEXT_DELTA") | .content'

# Run without saving the session
shr --mode json --no-session "Quick one-off question"

# Dry-run to see what tools would be called
shr --mode json --dry-run "Delete all .tmp files in the current directory"

gRPC Mode

gRPC mode starts a persistent AgentService server. Each connecting client supplies a session_id and gets its own isolated agent. Sessions are saved to disk after each turn and reloaded automatically on reconnect.

# Start on the default port
shr --mode grpc

# Use a custom address
shr --mode grpc --grpc-addr :9090

The server responds to SIGINT/SIGTERM with a graceful shutdown: in-flight turns are allowed to finish (30 s timeout), all sessions are flushed to disk, then the listener closes.

Proto Definition

The service is defined in proto/sharur/v1/agent.proto. Generated Go stubs live in internal/gen/sharur/v1/. Regenerate with mage generate.

Key RPCs:

In-Process Transport

For the TUI and JSON modes, all internal communication also goes through this same protobuf boundary using a bufconn in-memory pipe — not a network socket. This means all three modes share identical code paths. See Service Architecture for details.

Skills

Skills are Markdown files that provide sharur with specialized, reusable instructions for specific tasks. When a skill is invoked, its content is sent as a user message to the agent along with any arguments you provide.

How Skills Work

When sharur starts, it scans the skill directories and adds a list of available skills to the system prompt. The agent knows which skills exist and their descriptions. You can explicitly invoke a skill with /skill:<name> from the TUI, or the agent may choose to invoke one automatically via the read tool or a specialized skill tool call.

When you invoke a skill via /skill:<name>, it is executed as a skill tool, which loads the content and sends it to the agent:

<skill name="refactor" location="/path/to/refactor/SKILL.md">
References are relative to /path/to/refactor/.

...skill content here...
</skill>

your additional arguments here

Skill Discovery Directories

sharur searches for skills in these locations (in order):

Skills with the same name in a project directory override global ones.

Skill File Formats

Simple: Single .md file

Create a .md file directly in a skills directory. The filename (without extension) becomes the skill name.

.sharur/skills/refactor.md

Invoke with:

/skill:refactor improve error handling

Structured: Directory with SKILL.md

Create a directory containing a SKILL.md file. The directory name becomes the skill name. This format lets you include supporting files (examples, templates) alongside the skill.

.sharur/skills/
  code-review/
    SKILL.md
    checklist.md
    examples/
      before.go
      after.go

Invoke with:

/skill:code-review

Note: When a SKILL.md is found in a directory, subdirectories are not scanned further. This lets you bundle reference files with your skill.

Frontmatter (Optional)

Both formats support optional YAML frontmatter to provide metadata:

---
name: refactor
description: Refactor Go code to use idiomatic patterns and interfaces
---

You are an expert Go developer. When asked to refactor code:

1. Identify opportunities to use interfaces for testability
2. Replace repetitive code with helper functions
3. Add godoc comments to all exported symbols
4. Ensure error handling follows Go conventions (wrap with %w)

Always explain the reasoning behind each change before making it.

Frontmatter fields:

Practical Examples

Code Review Skill

.sharur/skills/code-review.md

---
name: code-review
description: Perform a thorough code review with actionable feedback
---

Review the provided code and evaluate it against these criteria:

**Correctness**
- Does the logic match the intended behavior?
- Are edge cases handled?
- Are there potential nil pointer dereferences or index out-of-bounds issues?

**Maintainability**
- Is the code readable and self-documenting?
- Are functions focused on a single responsibility?
- Is there appropriate error handling?

**Performance**
- Are there obvious inefficiencies (e.g. unnecessary allocations, N+1 queries)?

Format your response as:
## Summary
<one paragraph>

## Issues
<numbered list of specific issues with file:line references>

## Suggestions
<numbered list of improvements>

Invoke:

/skill:code-review

Or attach a file reference:

/skill:code-review @[internal/agent/loop.go]

Structured Skill with Supporting Files

.sharur/skills/
  db-migration/
    SKILL.md
    schema-example.sql

---
name: db-migration
description: Generate SQL migration files following our project conventions
---

Generate a database migration for the requested schema change.

Our migration file conventions:
- Files are named: `YYYYMMDD_HHMMSS_description.sql`
- Each file has an `-- +migrate Up` and `-- +migrate Down` section
- All tables use `BIGINT` primary keys with `AUTO_INCREMENT`
- Always include `created_at` and `updated_at` TIMESTAMP columns

See the example schema at the path listed in this skill's location directory: `schema-example.sql`

Global Utility Skill

~/.sharur/skills/explain.md

---
name: explain
description: Explain code clearly for a non-expert audience
---

Explain the following code in plain English. Assume the reader is a competent programmer but unfamiliar with this codebase.

Structure your explanation as:
1. **Purpose** — What does this code do in one sentence?
2. **How it works** — Step-by-step walkthrough of the logic
3. **Key concepts** — Any domain-specific terms or patterns used
4. **Gotchas** — Anything surprising or non-obvious

Tips

• Keep skills focused. One skill = one task type. Compose them with arguments rather than making a single skill do everything.
• Use relative file references — when your skill body references files, note they resolve relative to the skill’s directory. The agent is told the skill’s location so it can use the read tool on supporting files.
• Test your skill by invoking it with /skill:<name> in the TUI. The skill’s content and its effect on the conversation will be visible in the tool output cards.
• Override skills per-project — place a skill with the same name in .sharur/skills/ to override the global version for a specific project.

Prompt Templates

Prompt templates are reusable text snippets that expand directly into the TUI input editor. Unlike skills (which are sent to the agent immediately), prompt templates let you pre-fill the editor so you can review, edit, or complete the text before sending.

How Prompt Templates Work

When you type /prompt:<name> and press Enter, the template content is loaded into the editor input. You can then modify it, add context, attach files with @, and send it normally. This is useful for long, structured prompts you use frequently.

Prompt Template Directories

sharur searches these locations (in order):

Template File Format

A prompt template is any .md file in a prompts directory. The filename (without extension) is the template name.

.sharur/prompts/bug-report.md

Invoke with:

/prompt:bug-report

Minimal Template (no frontmatter)

The entire file content becomes the template text:

Describe the bug you found:

**Steps to reproduce:**
1.
2.
3.

**Expected behavior:**

**Actual behavior:**

**Environment:**
- OS:
- shr version:
- Model:

Template with Frontmatter

Add optional YAML frontmatter for metadata:

---
description: Generate a structured bug report
argument-hint: <component-name>
---

Describe the bug you found in the $1 component:

**Steps to reproduce:**
1.
2.
3.

**Expected behavior:**

**Actual behavior:**

Frontmatter fields:

Argument Substitution

Templates support positional argument placeholders: $1, $2, etc.

When you invoke a template via the slash command handler (not the interactive TUI), arguments after the template name are substituted. To mitigate prompt injection, sharur automatically wraps these arguments in <untrusted_input> tags. In the TUI, the template expands as-is and you fill in the values manually.

Practical Examples

PR Description Template

.sharur/prompts/pr-description.md

---
description: Generate a pull request description
---

Write a pull request description for the following changes.

**Format:**
## Summary
<What does this PR do? Why?>

## Changes
<Bullet list of specific changes>

## Testing
<How was this tested?>

## Notes
<Anything reviewers should pay attention to>

The diff is:

Invoke:

/prompt:pr-description

Then paste or attach the diff before sending.

Architecture Decision Record

.sharur/prompts/adr.md

---
description: Draft an Architecture Decision Record (ADR)
argument-hint: <decision-title>
---

Draft an Architecture Decision Record (ADR) for: **$1**

Use this structure:

# ADR: $1

## Status
Proposed

## Context
<What is the issue motivating this decision?>

## Decision
<What was decided?>

## Consequences
### Positive
-

### Negative
-

### Neutral
-

## Alternatives Considered
<What other approaches were evaluated and why were they rejected?>

Invoke:

/prompt:adr Use JSONL for session storage

Global Commit Message Template

~/.sharur/prompts/commit.md

---
description: Generate a conventional commit message
---

Generate a commit message following the Conventional Commits specification for the following diff or description of changes.

Format:
` ` `
<type>(<scope>): <short description>

<body: what changed and why, wrapped at 72 chars>

<footer: breaking changes, issue references>
` ` `

Types: feat, fix, docs, style, refactor, perf, test, chore

Changes:

Invoke:

/prompt:commit

Code Explanation for PR Comments

.sharur/prompts/explain-for-review.md

---
description: Explain a code block suitable for a PR comment
---

Explain the following code in a way that's suitable for a GitHub PR review comment. Be concise (2-4 sentences max), assume the reader is a senior engineer, and highlight any non-obvious design decisions.

Code:

Tips

• Prompt templates are for your input. They expand into the editor, not directly to the agent. This gives you a chance to customize before sending.
• Use $1, $2 placeholders for dynamic parts you’ll always fill in differently. Leave static boilerplate as literal text.
• Combine with @ file attachments. Type /prompt:code-review then add @src/myfile.go before pressing Enter to attach a file.
• Project-specific overrides. A template in .sharur/prompts/ with the same name as a global template takes priority for that project.
• Organize with subdirectories. Templates are discovered recursively, so you can group them:

  .sharur/prompts/
    code/
      refactor.md
      review.md
    docs/
      readme.md
      adr.md

  Invoke as /prompt:refactor, /prompt:adr, etc. (name is the filename, not the full path).

Go Extensions

Extensions let you add new behaviors to sharur beyond what’s possible with skills and prompt templates. They can observe and modify every stage of the agent loop — from the raw user input through each LLM turn and tool call to compaction and session teardown. Extensions run as separate processes and communicate with sharur via gRPC.

Extension Types

All extension types use the same gRPC protocol. The loader treats .py files specially (runs them with the configured Python interpreter), and everything else is executed directly as a binary.

Extension Discovery

Extensions are loaded from directories listed in your config under extensions:

// .sharur/config.json
{
  "extensions": [".sharur/extensions"]
}

Or globally in ~/.sharur/config.json.

Place your extension binary or script in the configured directory. sharur will automatically discover and launch it on startup.

You can also load a specific extension at runtime with the --extension flag:

shr --extension /path/to/my-extension "Your prompt here"

The Plugin Interface

Every Go extension implements the extensions.Plugin interface from github.com/goppydae/sharur/extensions. Embed extensions.NoopPlugin and override only the hooks you need.

Load-time hooks

Session lifecycle hooks

reason is "new" for a fresh session and "resume" for one loaded from disk.

Agent loop hooks

Transformation hooks

Key behaviors:

• ModifyInput returns agent.InputResult. Set Action to "continue" (pass through unchanged), "transform" (use the Text field instead), or "handled" (consume the message entirely — it is not appended to the transcript and the agent does not run).
• ModifyContext and BeforeProviderRequest work with JSON strings at the gRPC boundary. The GRPCClient marshals/unmarshals the Go structs automatically.
• BeforeCompact returns "" (empty) to let the default LLM summarization run, or a non-empty summary string to provide your own and skip the LLM call. The prep argument includes the message count, estimated token count, and the previous summary (if any).
• BeforeToolCall returns (ToolResult, true) to intercept (the tool does not execute), or (ToolResult{}, false) to allow normal execution.

Example: Git Context Injection

// .sharur/extensions/git-context/main.go
package main

import (
    "context"
    "fmt"
    "os/exec"
    "strings"

    "github.com/goppydae/sharur/extensions"
)

type GitContextPlugin struct {
    extensions.NoopPlugin
}

func (p *GitContextPlugin) BeforePrompt(_ context.Context, state extensions.AgentState) extensions.AgentState {
    branch := gitOutput("rev-parse", "--abbrev-ref", "HEAD")
    status := gitOutput("status", "--short")
    log := gitOutput("log", "--oneline", "-5")

    state.SystemPrompt += fmt.Sprintf(
        "\n\n<git_context>\nBranch: %s\n\nRecent commits:\n%s\n\nWorking tree:\n%s\n</git_context>",
        branch, log, status,
    )
    return state
}

func gitOutput(args ...string) string {
    out, err := exec.Command("git", args...).Output()
    if err != nil {
        return "(unavailable)"
    }
    return strings.TrimSpace(string(out))
}

func main() {
    extensions.Serve(&GitContextPlugin{
        NoopPlugin: extensions.NoopPlugin{NameStr: "git-context"},
    })
}

Build and auto-discover:

cd .sharur/extensions/git-context && go build -o ../git-context .

Example: Session Lifecycle Hooks

type AuditPlugin struct {
    extensions.NoopPlugin
    log *os.File
}

func (p *AuditPlugin) SessionStart(_ context.Context, sessionID string, reason agent.SessionStartReason) {
    p.log, _ = os.OpenFile(fmt.Sprintf("/tmp/sharur-%s.log", sessionID[:8]), os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    fmt.Fprintf(p.log, "session %s (%s)\n", sessionID, reason)
}

func (p *AuditPlugin) SessionEnd(_ context.Context, sessionID string, _ agent.SessionEndReason) {
    if p.log != nil {
        p.log.Close()
    }
}

func (p *AuditPlugin) AfterProviderResponse(_ context.Context, content string, numToolCalls int) {
    fmt.Fprintf(p.log, "response: %d chars, %d tool calls\n", len(content), numToolCalls)
}

Example: Input Transformation

ModifyInput runs before the user text is added to the transcript. Return "handled" to consume shortcuts silently, or "transform" to rewrite the text:

func (p *MyPlugin) ModifyInput(_ context.Context, text string) agent.InputResult {
    if strings.HasPrefix(text, "?quick ") {
        return agent.InputResult{
            Action: agent.InputTransform,
            Text:   "Respond in one sentence: " + text[7:],
        }
    }
    if text == "ping" {
        return agent.InputResult{Action: agent.InputHandled}
    }
    return agent.InputResult{Action: agent.InputContinue}
}

Example: Custom Compaction

Return a non-nil *agent.CompactionResult from BeforeCompact to supply your own summary and bypass the default LLM-based summarization:

func (p *MyPlugin) BeforeCompact(_ context.Context, prep agent.CompactionPrep) *agent.CompactionResult {
    if prep.EstimatedTokens < 50000 {
        return nil
    }
    summary := callCheaperModel(prep.PreviousSummary, prep.MessageCount)
    return &agent.CompactionResult{
        Summary: summary,
    }
}

Example: Extension with Custom Tools

Extensions can contribute tools the agent calls just like built-in tools:

type CounterPlugin struct {
    extensions.NoopPlugin
}

func (p *CounterPlugin) Tools() []extensions.ToolDefinition {
    return []extensions.ToolDefinition{
        {
            Name:        "count_lines",
            Description: "Count lines in a string",
            Schema:      json.RawMessage(`{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}`),
            IsReadOnly:  true,
        },
    }
}

func (p *CounterPlugin) ExecuteTool(_ context.Context, name string, args json.RawMessage) extensions.ToolResult {
    if name != "count_lines" {
        return extensions.ToolResult{Content: "unknown tool", IsError: true}
    }
    var input struct{ Text string `json:"text"` }
    _ = json.Unmarshal(args, &input)
    n := strings.Count(input.Text, "\n") + 1
    return extensions.ToolResult{Content: fmt.Sprintf("%d lines", n)}
}

Example: Intercepting Tool Calls (Sandbox)

BeforeToolCall lets you block or replace any built-in tool call:

type SandboxPlugin struct {
    extensions.NoopPlugin
    AllowedDir string
}

func (p *SandboxPlugin) BeforeToolCall(_ context.Context, call extensions.ToolCall, args json.RawMessage) (extensions.ToolResult, bool) {
    var input struct{ Path string `json:"path"` }
    _ = json.Unmarshal(args, &input)
    if input.Path != "" && !strings.HasPrefix(input.Path, p.AllowedDir) {
        return extensions.ToolResult{
            Content: fmt.Sprintf("blocked: %s is outside %s", input.Path, p.AllowedDir),
            IsError: true,
        }, true
    }
    return extensions.ToolResult{}, false
}

See examples/sandbox/ for a complete standalone implementation.

Extension Lifecycle

flowchart TD
    Start["shr startup"] --> Scan["Scan extension directories"]
    Scan --> Launch["Launch subprocess
SHARUR_SOCKET_PATH=..."]
    Launch --> Socket["Wait for socket · dial gRPC"]
    Socket --> Init["Name() · Tools()"]

    Init --> SS["SessionStart(sessionID, reason)
on new session or resume"]

    SS --> MI["ModifyInput(text)"]
    MI --> AS["AgentStart()"]

    subgraph turn ["Per LLM turn (repeats until no tool calls)"]
        direction TB
        T1["BeforePrompt() · ModifySystemPrompt()
ModifyContext() · BeforeProviderRequest()"]
        T2[/"LLM streams"/]
        T3["AfterProviderResponse() · TurnStart()"]
        subgraph toolloop ["Per tool call"]
            BTC["BeforeToolCall()"] --> Intercept{"intercept?"}
            Intercept -->|yes| CustomResult["return custom ToolResult"]
            Intercept -->|no| Exec["execTool() · AfterToolCall()"]
        end
        TE["TurnEnd()"]
        T1 --> T2 --> T3 --> toolloop --> TE
    end

    AS --> turn
    turn --> AE["AgentEnd()"]

    subgraph compact ["On compaction (auto or /compact)"]
        direction TB
        BC["BeforeCompact(prep)"] --> CustomSummary{"return non-nil?"}
        CustomSummary -->|yes| SkipLLM["skip LLM summarization"]
        CustomSummary -->|no| LLMSum["LLM summarizes"]
        SkipLLM --> AC["AfterCompact(freedTokens)"]
        LLMSum --> AC
    end

    AE --> SE["SessionEnd(sessionID, reason)
on session reset"]
    SE --> Shutdown["shr shutdown · kill subprocess"]

In-Process Go Extension (Advanced)

If your extension is written in Go and you control the build, you can implement agent.Extension directly via the SDK and register it without the gRPC overhead:

import (
    "github.com/goppydae/sharur/internal/agent"
    "github.com/goppydae/sharur/internal/tools"
)

type MyExtension struct {
    agent.NoopExtension
}

func (e *MyExtension) AgentStart(ctx context.Context) {
    log.Println("agent started")
}

func (e *MyExtension) ModifyInput(ctx context.Context, text string) agent.InputResult {
    if text == "ping" {
        return agent.InputResult{Action: agent.InputHandled}
    }
    return agent.InputResult{Action: agent.InputContinue}
}

func (e *MyExtension) ModifySystemPrompt(prompt string) string {
    return prompt + "\n\nAlways respond in bullet points."
}

func (e *MyExtension) BeforeToolCall(ctx context.Context, call *agent.ToolCall, args json.RawMessage) (*tools.ToolResult, bool) {
    if call.Name == "bash" {
        return &tools.ToolResult{Content: "bash is disabled", IsError: true}, true
    }
    return nil, false
}

Pass the extension via ag.SetExtensions() from the SDK or directly in cmd/shr.

Tips

• Extensions are isolated processes. A crash in an extension will not crash sharur — the loader catches errors and logs them.
• Keep BeforePrompt and ModifySystemPrompt fast. They run before every single LLM call. Cache data when possible; avoid blocking network calls.
• ModifyContext does not affect the stored transcript. Changes to the message slice are only visible to the LLM for that turn.
• Use skills for static context. If you only need to append static text to the system prompt, a skill is simpler than an extension.
• Extensions are global. All extensions in the configured directories are loaded for every session. There is no per-project scoping beyond the directory config.
• Logs go to stderr. Stdout is not read by the host; stderr is passed through for debugging.
• InputHandled stops all further processing. No agent turn is started, no message is appended to the transcript.
• BeforeCompact fires before the LLM call. Return nil to let the default summarizer run. Return a *CompactionResult to supply your own summary — useful for using a cheaper model or domain-specific logic.

Python Extensions

Python extensions use the same gRPC protocol as Go extensions. The loader detects .py files and runs them with the configured Python interpreter, passing SHARUR_SOCKET_PATH as an environment variable. The extension is expected to listen on that Unix socket.

Prerequisites

pip install grpcio grpcio-tools

Generate Python Stubs

python -m grpc_tools.protoc \
  -I extensions/proto \
  --python_out=.sharur/extensions \
  --grpc_python_out=.sharur/extensions \
  extensions/proto/extension.proto

This deposits extension_pb2.py and extension_pb2_grpc.py alongside your script.

Implement the Extension

# .sharur/extensions/ticket_context.py
import os
import subprocess
import grpc
from concurrent import futures
import extension_pb2
import extension_pb2_grpc


class TicketContextServicer(extension_pb2_grpc.ExtensionServicer):
    def Name(self, request, context):
        return extension_pb2.NameResponse(name="ticket-context")

    def Tools(self, request, context):
        return extension_pb2.ToolsResponse(tools=[])

    def BeforePrompt(self, request, context):
        branch = subprocess.check_output(
            ["git", "rev-parse", "--abbrev-ref", "HEAD"], text=True
        ).strip()
        state = request.state or extension_pb2.AgentState()
        state.prompt += f"\n\n<branch>Current branch: {branch}</branch>"
        return extension_pb2.BeforePromptResponse(state=state)

    def BeforeToolCall(self, request, context):
        return extension_pb2.BeforeToolCallResponse(intercept=False)

    def AfterToolCall(self, request, context):
        return extension_pb2.AfterToolCallResponse(result=request.result)

    def ModifySystemPrompt(self, request, context):
        return extension_pb2.ModifySystemPromptResponse(
            modified_prompt=request.current_prompt
        )

    def AgentStart(self, request, context):
        return extension_pb2.Empty()

    def AgentEnd(self, request, context):
        return extension_pb2.Empty()

    def ModifyInput(self, request, context):
        return extension_pb2.ModifyInputResponse(action="continue", text=request.text)


def serve():
    socket_path = os.environ["SHARUR_SOCKET_PATH"]
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    extension_pb2_grpc.add_ExtensionServicer_to_server(TicketContextServicer(), server)
    server.add_insecure_port(f"unix:{socket_path}")
    server.start()
    server.wait_for_termination()


if __name__ == "__main__":
    serve()

Place the script in your extensions directory. sharur runs it as python ticket_context.py on startup.

Available RPC Methods

Implement any subset of the ExtensionServicer methods. Unimplemented methods should return a sensible empty response (see the template above). The full list mirrors the Go plugin interface — see Go Extensions for hook semantics.

Tips

• Logs go to stderr. Python’s print() goes to stdout, which is not read by the host. Use sys.stderr.write() or logging for debugging output.
• Keep proto stubs in the same directory as your script, or adjust sys.path before importing them.
• Thread safety: grpc.server with ThreadPoolExecutor handles concurrent RPC calls. If you maintain per-session state, use a lock or session-keyed dict.

gRPC Extensions

gRPC extensions run as separate processes. sharur manages their lifecycle: launching the binary, passing the socket path, waiting for readiness, dialing, and killing on shutdown. The extension communicates entirely over a Unix Domain Socket using the generated proto stubs in extensions/proto/extension.proto.

How It Works

sequenceDiagram
    participant Loader as shr Loader
    participant Ext as Extension process
    participant Client as gRPC client

    Loader->>Ext: exec binary/script
    note over Ext: env: SHARUR_SOCKET_PATH=/tmp/...sock
    Ext->>Ext: net.Listen("unix", socketPath)
    note over Ext: signals readiness by listening
    Loader->>Loader: poll for socket file
    Loader->>Client: dial gRPC over Unix socket
    Client->>Ext: Name()
    Ext-->>Client: "my-extension"
    Client->>Ext: Tools()
    Ext-->>Client: [ToolDefinition, ...]
    note over Loader,Ext: extension registered — hooks active for all sessions

The extension must call net.Listen("unix", os.Getenv("SHARUR_SOCKET_PATH")) and start serving before shr times out.

Writing a Go Extension

Import github.com/goppydae/sharur/extensions — no internal packages needed.

package main

import "github.com/goppydae/sharur/extensions"

type myPlugin struct {
    extensions.NoopPlugin
}

func (p *myPlugin) ModifySystemPrompt(prompt string) string {
    return prompt + "\n\nAlways respond in haiku."
}

func main() {
    extensions.Serve(&myPlugin{
        NoopPlugin: extensions.NoopPlugin{NameStr: "haiku"},
    })
}

extensions.Serve handles the socket path, gRPC server setup, and graceful shutdown. extensions.NoopPlugin provides no-op defaults for every method.

Build and place the binary in a configured extensions directory:

go build -o .sharur/extensions/haiku .

Or load at runtime:

shr --extension .sharur/extensions/haiku

Plugin Interface

All hooks map 1:1 to agent.Extension. See Go Extensions for full hook semantics and examples.

Load-time:

Session lifecycle:

reason is "new" or "resume".

Proto Definition

The extension service is defined in extensions/proto/extension.proto. Generated Go stubs are in extensions/gen/. Regenerate with mage generate.

Python stubs can be generated with:

python -m grpc_tools.protoc \
  -I extensions/proto \
  --python_out=.sharur/extensions \
  --grpc_python_out=.sharur/extensions \
  extensions/proto/extension.proto

Tool Read-Only Semantics

Tool definitions returned by Tools() have an IsReadOnly bool field. Set it to true for tools that are safe in dry-run mode. The GRPCClient propagates this to the internal RemoteTool.IsReadOnly() so dry-run and sandbox extensions honour it correctly.

Debugging

• Logs go to stderr. The host passes the subprocess’s stderr through. Use log.Println or fmt.Fprintln(os.Stderr, ...) for debug output.
• Crashes are isolated. A panicking extension does not crash shr — the loader catches errors and logs them.
• Socket timeout. If the extension doesn’t listen within the timeout, the loader logs an error and skips it. Ensure extensions.Serve (or your own net.Listen + grpc.Serve) is called promptly in main().
• Test in isolation. Set SHARUR_SOCKET_PATH=/tmp/test.sock and run your extension binary directly; then grpcurl the socket to verify RPCs before integrating with shr.

Agent Loop

The agent is driven by an event-bus (internal/events). Every meaningful state transition emits an agent.Event to all subscribers.

EventBus Performance

The EventBus is async and non-blocking. Publish() enqueues to a 4096-item buffered channel per subscriber and returns immediately — it never blocks the agent loop. Each subscriber runs in its own goroutine. Slow subscribers drop events to protect the agent loop from backpressure.

Event Flow

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Tools

    User->>Agent: Prompt(text)
    Agent->>Agent: EventAgentStart
    loop each LLM turn
        Agent->>Agent: EventTurnStart · EventMessageStart
        Agent->>LLM: provider.Stream()
        LLM-->>Agent: EventTextDelta (×n)
        LLM-->>Agent: EventThinkingDelta (×n, if thinking enabled)
        LLM-->>Agent: EventToolCall (×n, if tools requested)
        Agent->>Agent: EventMessageEnd
        loop each tool call
            Agent->>Tools: execTool()
            Tools-->>Agent: EventToolDelta (streaming)
            Agent->>Agent: EventToolOutput
        end
        Agent->>Agent: EventTurnEnd
    end
    Agent->>Agent: EventAgentEnd

State Machine

The agent transitions through explicit states to prevent concurrent modification:

stateDiagram-v2
    [*] --> Idle
    Idle --> Thinking : Prompt()
    Thinking --> Executing : tool calls present
    Thinking --> Idle : no tool calls
    Thinking --> Compacting : token limit reached
    Thinking --> Aborting : Abort() called
    Executing --> Thinking : more turns needed
    Executing --> Idle : done
    Compacting --> Thinking : resume
    Aborting --> Idle
    Thinking --> Error
    Error --> [*]

Prompt Queues

Two queues support non-blocking interaction while the agent is running:

• SteerQueue — Injected as a user message at the next tool boundary (interrupt-style)
• FollowUpQueue — Processed as a new turn after the agent goes Idle

Tool System

Tools implement a simple interface:

type Tool interface {
    Name() string
    Description() string
    Schema() json.RawMessage
    Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
    IsReadOnly() bool
}

A ToolRegistry holds all registered tools. During a turn, when the LLM emits a tool call, execTool looks up the tool by name, executes it, and streams partial output via EventToolDelta before emitting the final EventToolOutput.

Built-in tools: read, write, edit, bash, grep, ls, find

Safety Enforcements

• Dry-Run Mode: When DryRun is enabled, any tool that is not marked as read-only will bypass execution and return a descriptive preview of what it would have done.
• Input Sanitization: Prompt template expansion automatically wraps user inputs in <untrusted_input> tags to prevent prompt injection into the base instructions.

Service Architecture

sharur follows a Strict Protobuf Internal Architecture. Instead of UI modes calling Go functions directly, all interfaces are treated as clients of a central AgentService.

Protobuf Boundary

The interface between the UI and the core is defined in proto/sharur/v1/agent.proto. This boundary ensures:

• Consistency: All modes (TUI, CLI, JSON, Remote gRPC) use the exact same code paths and logic.
• Decoupling: UI logic is completely isolated from agent state, session persistence, and provider adapters.
• Interoperability: Any gRPC-capable client can interact with a sharur service.

In-Process Communication

For local CLI usage, sharur uses a specialized In-Process Client (internal/service/client.go). It uses bufconn to implement the pb.AgentServiceClient interface over an in-memory pipe. This provides the safety and structure of gRPC without the latency or configuration complexity of network ports.

Backend Service (internal/service)

The Service struct implements pb.AgentServiceServer. It owns the session.Manager and manages the lifecycle of agent.Agent instances. It translates between internal agent events (Go channels) and Protobuf event streams.

Session Loading Strategy

RPCs split into three lookup strategies:

This means a /resume <id> command can switch to any session ever saved to disk without a round-trip NewSession call: the first GetMessages or GetState call transparently loads it.

LLM Providers

Provider Interface

type Provider interface {
    Stream(ctx context.Context, req *CompletionRequest) (<-chan *Event, error)
    Info() ProviderInfo
}

All providers return a uniform Stream of Event values — text deltas, thinking deltas, tool calls, and usage. The agent’s consumeStream function normalizes these into the internal Message format, making the agent completely provider-agnostic.

CompletionRequest

type CompletionRequest struct {
    Model       string
    Messages    []types.Message
    Tools       []types.ToolInfo
    System      string
    Thinking    types.ThinkingLevel
    MaxTokens   int
    Temperature float64
    StreamOpts  StreamOptions
}

The BeforeProviderRequest extension hook receives this struct as JSON and can modify any field before it is sent to the provider — useful for overriding temperature, trimming the tool list, or adjusting MaxTokens per request.

ProviderInfo

type ProviderInfo struct {
    Name          string
    Model         string
    MaxTokens     int
    ContextWindow int  // 0 = unknown
    HasToolCall   bool
    HasImages     bool
}

Info() is called once at startup. The service uses ContextWindow to trigger compaction when the conversation grows too large. HasImages controls whether the TUI offers image attachment UI.

ModelLister

type ModelLister interface {
    ListModels() ([]string, error)
}

All five adapters implement ModelLister. When --list-models is passed, the CLI casts the active provider to ModelLister and prints the result. Each adapter queries the appropriate API:

Supported Providers

Each adapter lives in internal/llm/ and translates the provider’s wire format into the uniform Stream abstraction.

Feature Matrix

Per-Provider Notes

Ollama

The Ollama adapter uses the /api/chat endpoint with streaming enabled. Context window defaults to 4096 when not reported by the server. Thinking is supported on models that emit <think> tokens (e.g. qwq, deepseek-r1) — sharur surfaces these as EventThinkingDelta events by detecting the tag boundaries in the stream.

llama.cpp

Uses the OpenAI-compatible /v1/chat/completions endpoint. The context window (n_ctx) is queried from the server at startup. Image attachments are not supported because llama.cpp’s OpenAI endpoint does not accept multipart vision payloads in the standard format.

OpenAI

Uses the standard /v1/chat/completions streaming endpoint. Any server implementing this API — vLLM, LM Studio, Groq, Together AI — can be used by setting openAIBaseURL. Reasoning models (o3, o4-mini) emit reasoning_content deltas that are surfaced as EventThinkingDelta.

Anthropic

Uses the Messages API (/v1/messages) with streaming. Extended thinking is activated when req.Thinking is medium or high:

• medium — 10,000-token thinking budget
• high — 20,000-token thinking budget

The API requires temperature: 1.0 when extended thinking is enabled; the adapter sets this automatically and overrides any user-supplied temperature for that request.

Google

Uses the Gemini generateContent API via the google.golang.org/genai client library. Gemini 1.5 Pro and later have context windows of 1M+ tokens; compaction is rarely triggered for typical sessions.

Adding a Provider

Implement the Provider interface in internal/llm/yourprovider.go and register it in internal/config/factory.go. Implement ModelLister to enable --list-models. The adapter receives a fully-formed CompletionRequest; it is responsible for translating Message.ToolCalls and Message.Images into the target API’s format.

Session Management

Sessions are persisted as JSONL files in a project-aware directory:

~/.sharur/sessions/
  --Users-alice-Projects-myapp--/     ← sanitized CWD
    2026-04-23T07-06-54_{uuid}.jsonl  ← timestamped session file
    2026-04-23T09-12-11_{uuid}.jsonl

Session File Format

Each .jsonl file contains one JSON object per line:

• Line 0 (header): kind=header — session ID, parentId, model, timestamps, system prompt, compaction settings, dryRun flag
• Subsequent lines: kind=message — individual conversation messages with full payloads (role, content, thinking, tool calls, tool call ID)

Session Tree

Sessions form a linked tree via parentId. The session.Manager.BuildTree() method assembles all sessions from the project directory into a []*TreeNode tree. FlattenTree produces a depth-first flat list with structured layout metadata (gutters, connectors, indentation), which the TUI layer uses to render a clean Unicode box-drawing tree diagram.

flowchart TD
    A["Session A
(root)"] --> B["Session B
(/branch from A)"]
    A --> C["Session C
(/fork of A)"]
    B --> D["Session D
(/branch from B at msg 5)"]
    B --> E["Session E
(/rebase of B)"]
    B --> F["Session F
(/merge into B)"]

    style C stroke-dasharray: 5 5

/fork creates an independent copy (dashed border above) with no parentId link — it does not appear as a child in the tree visualization.

Branching, Rebasing & Merging

flowchart TD
    Q{"What do you need?"}

    Q -->|"Explore an alternate
path from this point"| Branch["/branch [idx]
Child session, same history up to idx"]
    Q -->|"Independent copy
no tree relationship"| Fork["/fork
Detached snapshot"]
    Q -->|"Clean up the conversation
keep only specific messages"| Rebase["/rebase
Interactively select messages
for a new session"]
    Q -->|"Combine two sessions
into one context"| Merge["/merge <id>
LLM-synthesized merge turn
appended to current session"]

The /tree modal (keyboard shortcut B, F, R on a selected session) exposes all of these without leaving the TUI.

Compaction & Context Management

To stay within LLM context windows, sharur implements an auto-compaction strategy:

1. Trigger: When tokens > ContextWindow - reserveTokens, compaction fires.
2. Summarization: The agent uses the LLM to generate a structured summary (<!-- sharur-summary -->) of the pruned messages.
3. File Tracking: The summary carries forward lists of files read and modified, so the assistant retains awareness of what it has already seen.
4. Split Turn Handling: If compaction cuts mid-turn, a “Turn Prefix Summary” is generated to preserve context for the remaining tool calls.
5. Session Tree Integration: Compaction events are stored as TypeCompaction records in the JSONL file, visible in /stats and preserved across restarts.

Compaction Configuration

// ~/.sharur/config.json or .sharur/config.json
{
  "compaction": {
    "enabled": true,
    "reserveTokens": 2048,
    "keepRecentTokens": 8192
  }
}

Trigger compaction manually at any time with /compact in the TUI or by calling the Compact RPC directly.

Export & Import

Sessions can be exported to and imported from JSONL files:

# Export from TUI
/export /path/to/session.jsonl

# Import into TUI (creates a new session from the file)
/import /path/to/session.jsonl

# Export from CLI without entering TUI
shr --export /path/to/session.html   # HTML snapshot

Exported JSONL files are self-contained: they include the session header and all messages. Imported sessions are assigned a new UUID and added to the current project’s session directory.

TUI Internals

The TUI is built with Bubble Tea (v2) and organized into focused files:

Prompt Submission

Prompt submission uses promptGRPC(), which opens a client.Prompt() server-streaming RPC and drains *pb.AgentEvent messages into m.eventCh in a goroutine. The listenForEvent Bubble Tea command feeds that channel back into the update loop one event at a time.

Prompt History

The TUI maintains a per-session prompt history in m.promptHistory, synced from the service via GetMessages at startup and after session switches. Users navigate previous prompts using Up/Down arrow keys while the editor is focused; the current draft is preserved as m.draftInput.

Render Data Model

The TUI stores conversation history as []historyEntry. Each entry has an ordered []contentItem slice that preserves the exact stream order:

historyEntry {
  role: "assistant"
  items: [
    { kind: contentItemThinking, text: "..." }
    { kind: contentItemText,     text: "..." }
    { kind: contentItemToolCall, tc: { id, name, arg, status, streamingOutput } }
    { kind: contentItemToolOutput, out: { toolCallID, content, isError } }
  ]
}

This mirrors the content[] array model, ensuring correct temporal ordering of thinking, text, and tool calls.

Modal System

• Stats — Token counts, session metadata, file/path info
• Config — Active model, provider, compaction settings
• Session Tree — Interactive paginated tree with structured branch visualization; supports Resume (Enter) and Branch (B)
• Rebase Picker — Selection interface for history manipulation
• Merge Picker — Fuzzy finder for selecting sessions to merge into the current conversation

Build & Release

sharur uses a combination of Mage and GitHub Actions for CI/CD.

Versioning

The project version is maintained in a VERSION file in the repository root. During build, Magefile.go reads this file and injects it into the binary using linker flags (-ldflags "-X main.version=...").

Mage Targets

CI/CD Pipelines

Continuous Integration (ci.yml)

Triggered on every push to main and all pull requests. Runs mage all within a Nix environment on both ubuntu-latest and macos-latest, then uploads per-platform binaries as build artifacts. Coverage is collected and summarised via go tool cover.

Automated Release (release.yml)

Triggered by pushing a version tag (e.g., v1.2.3). Runs mage release to build cross-platform assets and uses softprops/action-gh-release to publish them to a new GitHub Release.

Docs Deploy (docs.yml)

Triggered on push to main and on published releases. Runs mage docs (gomarkdoc + Hugo build) and deploys docs/public/ to the gh-pages branch via peaceiris/actions-gh-pages.

Quickstart

Import github.com/goppydae/sharur/sdk to embed an agent in any Go program.

import "github.com/goppydae/sharur/sdk"

ag, err := sdk.NewAgent(sdk.Config{
    Provider: "ollama",
    Model:    "llama3.2",
    Tools:    sdk.DefaultTools(),
})
if err != nil {
    panic(err)
}

ag.Subscribe(func(e sdk.Event) {
    if e.Type == sdk.EventTextDelta {
        fmt.Print(e.Content)
    }
})

ag.Prompt(context.Background(), "List the Go files in this directory")
<-ag.Idle()

Config Fields

type Config struct {
    Provider    string        // "ollama", "openai", "anthropic", "llamacpp", "google"
    Model       string        // model name or "provider/model"
    APIKey      string        // optional; env vars take priority
    BaseURL     string        // optional provider endpoint override
    Tools       []sdk.Tool    // sdk.DefaultTools() or custom list
    Extensions  []sdk.Extension
    SystemPrompt string
    ThinkingLevel sdk.ThinkingLevel
    SessionDir  string        // where to persist sessions
    DryRun      bool
}

Core API

Event Types

Subscribe to events by checking e.Type:

Minimal Example (no tools, no session)

ag, _ := sdk.NewAgent(sdk.Config{
    Provider: "anthropic",
    Model:    "claude-sonnet-4-6",
    APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
})

var buf strings.Builder
ag.Subscribe(func(e sdk.Event) {
    if e.Type == sdk.EventTextDelta {
        buf.WriteString(e.Content)
    }
})

ag.Prompt(context.Background(), "What is 2+2?")
<-ag.Idle()
fmt.Println(buf.String())

Custom Tools

Built-in Tools

Pass sdk.DefaultTools() in sdk.Config.Tools to get the full set of built-in tools:

bash, write, and edit are destructive. In --dry-run mode they preview what they would do without executing.

Tool Interface

Implement sdk.Tool to create a custom tool:

type Tool interface {
    Name() string
    Description() string
    Schema() json.RawMessage       // JSON Schema for the input parameters
    Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
    IsReadOnly() bool              // if true, tool is allowed in dry-run mode
}

ToolUpdate is a callback for streaming partial output while the tool runs:

type ToolUpdate func(content string)

Example: Custom Tool

type CountLinesTool struct{}

func (t *CountLinesTool) Name() string { return "count_lines" }
func (t *CountLinesTool) Description() string {
    return "Count the number of lines in a file"
}
func (t *CountLinesTool) Schema() json.RawMessage {
    return json.RawMessage(`{
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "File path to count lines in"}
        },
        "required": ["path"]
    }`)
}
func (t *CountLinesTool) IsReadOnly() bool { return true }

func (t *CountLinesTool) Execute(ctx context.Context, args json.RawMessage, update sdk.ToolUpdate) (*sdk.ToolResult, error) {
    var input struct {
        Path string `json:"path"`
    }
    if err := json.Unmarshal(args, &input); err != nil {
        return nil, err
    }
    data, err := os.ReadFile(input.Path)
    if err != nil {
        return &sdk.ToolResult{Content: err.Error(), IsError: true}, nil
    }
    n := strings.Count(string(data), "\n") + 1
    return &sdk.ToolResult{Content: fmt.Sprintf("%d lines", n)}, nil
}

Register alongside the built-in tools:

ag, _ := sdk.NewAgent(sdk.Config{
    Provider: "ollama",
    Model:    "llama3.2",
    Tools:    append(sdk.DefaultTools(), &CountLinesTool{}),
})

Selective Tools

Pass only the tools you want rather than the full default set:

tools := sdk.ToolsFor("read", "grep", "ls")   // subset by name

Or build the list manually to include only read-only tools for a sandboxed agent.

Events

The agent communicates state transitions via an event bus. Every meaningful action emits an sdk.Event to all registered subscribers.

Subscribing

ag.Subscribe(func(e sdk.Event) {
    switch e.Type {
    case sdk.EventTextDelta:
        fmt.Print(e.Content)
    case sdk.EventToolCall:
        fmt.Printf("[tool: %s]\n", e.ToolCall.Name)
    case sdk.EventAgentEnd:
        fmt.Println("\ndone")
    }
})

Multiple subscribers are allowed. Each runs in its own goroutine. The EventBus is non-blocking — Publish enqueues to a 4096-item buffered channel per subscriber and returns immediately, so slow subscribers drop events rather than stalling the agent loop.

Event Reference

Event Flow Per Prompt

EventAgentStart
  EventTurnStart
    EventMessageStart
      EventTextDelta*
      EventThinkingDelta*
      EventToolCall*
    EventMessageEnd
    [per tool call]
      EventToolDelta*
      EventToolOutput
  EventTurnEnd
  [repeat if tool calls triggered another turn]
EventAgentEnd

Agent State Machine

The agent transitions through explicit states visible via EventAgentStart/EventAgentEnd and the ag.Idle() channel:

Idle → Thinking → Executing → Idle
           ↓
       Compacting → Idle
           ↓
         Aborting → Idle

ag.Idle() returns a channel that closes when the agent returns to Idle. Use it to block until a prompt completes:

ag.Prompt(ctx, "Refactor main.go")
<-ag.Idle()
// agent is idle, safe to call Prompt again

In-Process Extensions

If your extension is written in Go and you control the build, you can implement sdk.Extension (an alias of agent.Extension) directly — no gRPC, no subprocess, no socket. This is the lowest-overhead extension path.

Attaching Extensions

type loggingExt struct {
    sdk.NoopExtension
}

func (e *loggingExt) AgentStart(ctx context.Context) { log.Println("agent started") }
func (e *loggingExt) AgentEnd(ctx context.Context)   { log.Println("agent finished") }
func (e *loggingExt) ModifyInput(ctx context.Context, text string) sdk.InputResult {
    if text == "quit" {
        return sdk.InputResult{Action: sdk.InputHandled}
    }
    return sdk.InputResult{Action: sdk.InputContinue}
}

ag.SetExtensions([]sdk.Extension{
    &loggingExt{NoopExtension: sdk.NoopExtension{NameStr: "logger"}},
})