feat: colored terminal rendering layer for agent loop steps

Add internal/render package with zero-dependency ANSI rendering:
- Iteration headers with model name (bold blue rules)
- Thinking text (dim italic)
- Tool calls with name + args (cyan)
- Tool results with truncation (green, max 2000 chars)
- Final answer (bold)
- Error output (red)

Features:
- Respects NO_COLOR env var + tty detection
- Nil renderer safe (programmatic API stays silent)
- 90.3% test coverage
- --no-color CLI flag to force-disable colors

Author: jkyberneees

cmd/kode/main.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/BackendStack21/kode"
+	"github.com/BackendStack21/kode/internal/render"
 )
 
 // version is set at build time via ldflags: -ldflags "-X main.version=v0.2.1"
@@ -53,6 +54,7 @@ type runFlags struct {
 	Thinking string
 	MaxIter  int
 	Sandbox  bool
+	NoColor  bool
 	Task     string
 }
 
@@ -83,6 +85,9 @@ func parseRunFlags(args []string) (runFlags, error) {
 		case "--sandbox":
 			f.Sandbox = true
 			i++
+		case "--no-color":
+			f.NoColor = true
+			i++
 		default:
 			// Not a flag — treat remaining as the task
 			goto done
@@ -107,6 +112,7 @@ Flags:
   --max-iter <n>       Max think->act cycles (default: 90)
   --thinking <level>   Reasoning depth: enabled|disabled (Deepseek) or low|medium|high (OpenAI o-series)
   --sandbox            Run in isolated Docker container
+  --no-color           Disable colored terminal output
   --system <prompt>    System prompt override`)
 }
 
@@ -134,6 +140,14 @@ func run(args []string) error {
 		sandboxCleanup = cleanup
 	}
 
+	// Create terminal renderer for colored step-by-step output.
+	modelName := f.Model
+	if modelName == "" {
+		modelName = "deepseek-chat"
+	}
+	color := !f.NoColor && render.ColorEnabled()
+	rend := render.New(os.Stderr, color)
+
 	agent, err := kode.New(kode.Config{
 		Model:          f.Model,
 		BaseURL:        f.BaseURL,
@@ -142,18 +156,13 @@ func run(args []string) error {
 		Thinking:       f.Thinking,
 		Tools:          tools,
 		SandboxCleanup: sandboxCleanup,
+		Renderer:       rend.WithModel(modelName),
 	})
 	if err != nil {
 		return err
 	}
 	defer agent.Close()
 
-	modelName := f.Model
-	if modelName == "" {
-		modelName = "deepseek-chat"
-	}
-	fmt.Fprintf(os.Stderr, "kode: %s thinking...\n", modelName)
-
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
@@ -177,14 +186,14 @@ func setupSandbox(tools []kode.Tool) (func() error, error) {
 	}
 
 	createCmd := exec.Command("docker", "run",
-		"--rm",                                  // destroy on exit
-		"--detach",                              // run in background
+		"--rm",     // destroy on exit
+		"--detach", // run in background
 		"--name", containerName,
-		"--cap-drop", "ALL",                     // no capabilities
-		"--security-opt", "no-new-privileges",   // no privilege escalation
-		"--network", "none",                     // no network
-		"--tmpfs", "/tmp:noexec",                // no executable temp files
-		"-v", wd+":/workspace",                  // working dir (read-write inside sandbox)
+		"--cap-drop", "ALL", // no capabilities
+		"--security-opt", "no-new-privileges", // no privilege escalation
+		"--network", "none", // no network
+		"--tmpfs", "/tmp:noexec", // no executable temp files
+		"-v", wd+":/workspace", // working dir (read-write inside sandbox)
 		"alpine:latest",
 		"sleep", "infinity",
 	)
@@ -208,11 +217,12 @@ func builtinTools() []kode.Tool {
 		&shellTool{},
 	}
 }
+
 // getVersion returns the version string. Resolution order:
-//   1. ldflags override (-X main.version=v0.2.1)
-//   2. VCS tag from debug.ReadBuildInfo (when built with go install)
-//   3. VCS revision (short commit hash)
-//   4. "dev" (local go build without VCS info)
+//  1. ldflags override (-X main.version=v0.2.1)
+//  2. VCS tag from debug.ReadBuildInfo (when built with go install)
+//  3. VCS revision (short commit hash)
+//  4. "dev" (local go build without VCS info)
 func getVersion() string {
 	if version != "" {
 		return version

cmd/kode/main_test.go

@@ -415,8 +415,8 @@ func TestGetVersion_ReturnsNonEmpty(t *testing.T) {
 // Test parseRunFlags with edge cases.
 func TestParseRunFlags_EdgeCases(t *testing.T) {
 	tests := []struct {
-		name string
-		args []string
+		name  string
+		args  []string
 		check func(*testing.T, runFlags)
 	}{
 		{

internal/llm/client.go

@@ -67,12 +67,12 @@ type FunctionDef struct {
 
 // CallParams is the request body for /chat/completions.
 type CallParams struct {
-	Model          string          `json:"model"`
-	Messages       []Message       `json:"messages"`
-	Tools          []ToolDef       `json:"tools,omitempty"`
-	Stream         bool            `json:"stream"`
-	Thinking       *ThinkingConfig `json:"thinking,omitempty"`
-	ReasoningEffort string         `json:"reasoning_effort,omitempty"`
+	Model           string          `json:"model"`
+	Messages        []Message       `json:"messages"`
+	Tools           []ToolDef       `json:"tools,omitempty"`
+	Stream          bool            `json:"stream"`
+	Thinking        *ThinkingConfig `json:"thinking,omitempty"`
+	ReasoningEffort string          `json:"reasoning_effort,omitempty"`
 }
 
 // ThinkingConfig controls Deepseek's extended thinking feature.

internal/llm/client_test.go

@@ -100,9 +100,9 @@ func TestCallParamsMarshaling_ReasoningEffort(t *testing.T) {
 
 	for _, level := range tests {
 		body := CallParams{
-			Model:          "o1",
-			Messages:       []Message{{Role: "user", Content: "hello"}},
-			Stream:         false,
+			Model:           "o1",
+			Messages:        []Message{{Role: "user", Content: "hello"}},
+			Stream:          false,
 			ReasoningEffort: level,
 		}
 

internal/loop/loop.go

@@ -7,22 +7,25 @@ import (
 	"strings"
 
 	"github.com/BackendStack21/kode/internal/llm"
+	"github.com/BackendStack21/kode/internal/render"
 	"github.com/BackendStack21/kode/internal/tool"
 )
 
 // Engine runs the agent loop: observe → think → act → repeat.
 type Engine struct {
 	client   *llm.Client
 	registry *tool.Registry
+	renderer *render.Renderer // optional: colored terminal output
 	maxIter  int
 	system   string
 }
 
 // New creates a new loop Engine.
-func New(client *llm.Client, registry *tool.Registry, maxIterations int, systemMessage string) *Engine {
+func New(client *llm.Client, registry *tool.Registry, maxIterations int, systemMessage string, renderer *render.Renderer) *Engine {
 	return &Engine{
 		client:   client,
 		registry: registry,
+		renderer: renderer,
 		maxIter:  maxIterations,
 		system:   systemMessage,
 	}
@@ -46,6 +49,11 @@ func (e *Engine) Run(ctx context.Context, task string) (string, error) {
 		default:
 		}
 
+		// Render iteration header (1-indexed for humans)
+		if e.renderer != nil {
+			e.renderer.Iteration(i+1, e.maxIter)
+		}
+
 		// THINK
 		result, err := e.client.Call(ctx, messages, tools)
 		if err != nil {
@@ -54,9 +62,17 @@ func (e *Engine) Run(ctx context.Context, task string) (string, error) {
 
 		// No tool calls = final answer
 		if len(result.ToolCalls) == 0 {
+			if e.renderer != nil {
+				e.renderer.FinalAnswer(result.Content)
+			}
 			return result.Content, nil
 		}
 
+		// Render the model's thinking (reasoning before tool calls)
+		if e.renderer != nil && result.Content != "" {
+			e.renderer.Thinking(result.Content)
+		}
+
 		// Build assistant message with tool calls
 		assistantMsg := llm.Message{
 			Role:      "assistant",
@@ -67,6 +83,10 @@ func (e *Engine) Run(ctx context.Context, task string) (string, error) {
 
 		// ACT: execute each tool call
 		for _, tc := range result.ToolCalls {
+			if e.renderer != nil {
+				e.renderer.ToolCall(tc.Function.Name, tc.Function.Arguments)
+			}
+
 			t := e.registry.Get(tc.Function.Name)
 			output := fmt.Sprintf("error: tool %q not found", tc.Function.Name)
 			if t != nil {
@@ -78,6 +98,10 @@ func (e *Engine) Run(ctx context.Context, task string) (string, error) {
 				}
 			}
 
+			if e.renderer != nil {
+				e.renderer.ToolResult(output)
+			}
+
 			messages = append(messages, llm.Message{
 				Role:       "tool",
 				Content:    output,

internal/loop/loop_test.go

@@ -19,8 +19,8 @@ type fakeTool struct {
 	output      string
 }
 
-func (f *fakeTool) Name() string              { return f.name }
-func (f *fakeTool) Description() string       { return f.description }
+func (f *fakeTool) Name() string        { return f.name }
+func (f *fakeTool) Description() string { return f.description }
 func (f *fakeTool) Schema() any {
 	return map[string]any{
 		"type":       "object",
@@ -38,7 +38,7 @@ func TestEngine_Run_SimpleAnswer(t *testing.T) {
 
 	client := llm.New(server.URL, "sk-test", "test-model", "")
 	registry := tool.NewRegistry(nil)
-	engine := New(client, registry, 10, "")
+	engine := New(client, registry, 10, "", nil)
 
 	result, err := engine.Run(context.Background(), "Say hello")
 	if err != nil {
@@ -80,7 +80,7 @@ func TestEngine_Run_ToolCallLoop(t *testing.T) {
 	echoTool := &fakeTool{name: "echo", description: "echoes input", output: "hello output"}
 	registry := tool.NewRegistry([]tool.Tool{echoTool})
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, registry, 10, "")
+	engine := New(client, registry, 10, "", nil)
 
 	result, err := engine.Run(context.Background(), "Echo hello")
 	if err != nil {
@@ -117,7 +117,7 @@ func TestEngine_Run_MaxIterations(t *testing.T) {
 	echoTool := &fakeTool{name: "echo", description: "echo", output: "ok"}
 	registry := tool.NewRegistry([]tool.Tool{echoTool})
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, registry, 3, "")
+	engine := New(client, registry, 3, "", nil)
 
 	_, err := engine.Run(context.Background(), "Loop forever")
 	if err == nil {
@@ -132,7 +132,7 @@ func TestEngine_Run_ContextCancellation(t *testing.T) {
 	defer server.Close()
 
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, tool.NewRegistry(nil), 10, "")
+	engine := New(client, tool.NewRegistry(nil), 10, "", nil)
 
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // cancel immediately
@@ -166,7 +166,7 @@ func TestEngine_Run_SystemMessage(t *testing.T) {
 	defer server.Close()
 
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, tool.NewRegistry(nil), 10, "You are a test bot.")
+	engine := New(client, tool.NewRegistry(nil), 10, "You are a test bot.", nil)
 
 	result, err := engine.Run(context.Background(), "hi")
 	if err != nil {
@@ -198,7 +198,7 @@ func TestEngine_Run_ToolNotFound(t *testing.T) {
 
 	// No tools registered — the tool call will fail
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, tool.NewRegistry(nil), 10, "")
+	engine := New(client, tool.NewRegistry(nil), 10, "", nil)
 
 	// The loop should handle the missing tool gracefully — the tool error
 	// is fed back to the model as a tool response message. The test server
@@ -214,7 +214,7 @@ func TestEngine_BuildToolDefs(t *testing.T) {
 	t2 := &fakeTool{name: "write", description: "write files"}
 	registry := tool.NewRegistry([]tool.Tool{t1, t2})
 
-	engine := New(nil, registry, 10, "")
+	engine := New(nil, registry, 10, "", nil)
 	defs := engine.buildToolDefs()
 
 	if len(defs) != 2 {
@@ -239,7 +239,7 @@ func TestEngine_BuildToolDefs_StringSchema(t *testing.T) {
 	st := &stringSchemaTool{name: "custom", description: "custom tool", schemaStr: `{"type":"object"}`}
 	registry := tool.NewRegistry([]tool.Tool{st})
 
-	engine := New(nil, registry, 10, "")
+	engine := New(nil, registry, 10, "", nil)
 	defs := engine.buildToolDefs()
 
 	if len(defs) != 1 {
@@ -254,7 +254,7 @@ func TestEngine_BuildToolDefs_EmptyStringSchema(t *testing.T) {
 	st := &stringSchemaTool{name: "empty", description: "empty", schemaStr: ""}
 	registry := tool.NewRegistry([]tool.Tool{st})
 
-	engine := New(nil, registry, 10, "")
+	engine := New(nil, registry, 10, "", nil)
 	defs := engine.buildToolDefs()
 
 	if len(defs) != 1 {
@@ -270,9 +270,9 @@ type stringSchemaTool struct {
 	schemaStr   string
 }
 
-func (s *stringSchemaTool) Name() string              { return s.name }
-func (s *stringSchemaTool) Description() string       { return s.description }
-func (s *stringSchemaTool) Schema() any               { return s.schemaStr }
+func (s *stringSchemaTool) Name() string                     { return s.name }
+func (s *stringSchemaTool) Description() string              { return s.description }
+func (s *stringSchemaTool) Schema() any                      { return s.schemaStr }
 func (s *stringSchemaTool) Call(args string) (string, error) { return "ok", nil }
 
 // Test context cancellation inside the iteration loop (not before start).
@@ -304,7 +304,7 @@ func TestEngine_Run_ContextCancelDuringLoop(t *testing.T) {
 	echoTool := &fakeTool{name: "echo", description: "echo", output: "ok"}
 	registry := tool.NewRegistry([]tool.Tool{echoTool})
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, registry, 10, "")
+	engine := New(client, registry, 10, "", nil)
 
 	_, err := engine.Run(ctx, "task")
 	if err == nil {
@@ -335,7 +335,7 @@ func TestEngine_Run_ToolCallError(t *testing.T) {
 	failingTool := &errorTool{name: "failing", description: "always fails"}
 	registry := tool.NewRegistry([]tool.Tool{failingTool})
 	client := llm.New(server.URL, "sk-test", "test-model", "")
-	engine := New(client, registry, 10, "")
+	engine := New(client, registry, 10, "", nil)
 
 	// Tool error is fed back as a tool response; server only returns one
 	// response, so we hit max iterations.