feat(cli): add terminal turn logger (#34)

Author: lucasnevespereira

README.md

@@ -77,6 +77,12 @@ For structured turn logs, pass `-log-json`. Named agents append logs to `~/.viku
 vikusha chat -log-json writer
 ```
 
+For readable turn logs during a terminal session, pass `-log-terminal`.
+
+```bash
+vikusha chat -log-terminal writer
+```
+
 You can load the same character from Go.
 
 ```go

cmd/vikusha/main.go

@@ -66,9 +66,14 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) error {
 		userID := fs.String("user", os.Getenv("USER"), "user id for the conversation")
 		timeout := fs.Duration("timeout", 2*time.Minute, "timeout per turn")
 		logJSON := fs.Bool("log-json", false, "write structured turn logs to stderr")
+		logTerminal := fs.Bool("log-terminal", false, "write human-readable turn logs to stderr")
+		noColor := fs.Bool("no-color", false, "disable color in terminal turn logs")
 		if err := fs.Parse(args[1:]); err != nil {
 			return err
 		}
+		if *logJSON && *logTerminal {
+			return fmt.Errorf("-log-json and -log-terminal cannot be used together")
+		}
 		if fs.NArg() != 1 {
 			return fmt.Errorf("usage: vikusha %s <character.yaml|agent>", args[0])
 		}
@@ -90,6 +95,8 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) error {
 				logWriter = logFile
 			}
 			logger = agent.NewJSONLogger(logWriter)
+		} else if *logTerminal {
+			logger = agent.NewTerminalLogger(stderr, !*noColor)
 		}
 		a, err := buildAgent(path, logger)
 		if err != nil {

cmd/vikusha/main_test.go

@@ -33,6 +33,17 @@ func TestMissingCommand(t *testing.T) {
 	}
 }
 
+func TestLogModesAreMutuallyExclusive(t *testing.T) {
+	var out, errOut bytes.Buffer
+	err := run([]string{"chat", "-log-json", "-log-terminal", "character.yaml"}, strings.NewReader(""), &out, &errOut)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "-log-json and -log-terminal") {
+		t.Fatalf("error = %q, want log mode conflict", err)
+	}
+}
+
 func TestCreateAgent(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)

core/agent/log.go

@@ -3,7 +3,9 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"io"
+	"strings"
 	"sync"
 )
 
@@ -29,3 +31,66 @@ func (l *JSONLogger) LogTurn(ctx context.Context, event TurnEvent) {
 	defer l.mu.Unlock()
 	_, _ = l.w.Write(append(data, '\n'))
 }
+
+type TerminalLogger struct {
+	mu    sync.Mutex
+	w     io.Writer
+	color bool
+}
+
+func NewTerminalLogger(w io.Writer, color bool) *TerminalLogger {
+	return &TerminalLogger{w: w, color: color}
+}
+
+func (l *TerminalLogger) LogTurn(ctx context.Context, event TurnEvent) {
+	if l == nil || l.w == nil {
+		return
+	}
+
+	line := terminalTurnLine(event)
+	if l.color {
+		line = colorizeTurnLine(event, line)
+	}
+
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	_, _ = fmt.Fprintln(l.w, line)
+}
+
+func terminalTurnLine(event TurnEvent) string {
+	parts := []string{
+		fmt.Sprintf("turn %s", event.FinishReason),
+		fmt.Sprintf("duration=%s", event.Duration),
+		fmt.Sprintf("iterations=%d", event.Iterations),
+	}
+	if event.InputTokens > 0 || event.OutputTokens > 0 {
+		parts = append(parts, fmt.Sprintf("tokens=%d/%d", event.InputTokens, event.OutputTokens))
+	}
+	if event.CacheReadTokens > 0 || event.CacheWriteTokens > 0 {
+		parts = append(parts, fmt.Sprintf("cache=%d/%d", event.CacheReadTokens, event.CacheWriteTokens))
+	}
+	if event.ReasoningTokens > 0 {
+		parts = append(parts, fmt.Sprintf("reasoning=%d", event.ReasoningTokens))
+	}
+	if len(event.Tools) > 0 {
+		parts = append(parts, "tools="+strings.Join(event.Tools, ","))
+	}
+	if event.Truncated {
+		parts = append(parts, "truncated=true")
+	}
+	if event.Error != "" {
+		parts = append(parts, "error="+event.Error)
+	}
+	return strings.Join(parts, " ")
+}
+
+func colorizeTurnLine(event TurnEvent, line string) string {
+	switch event.FinishReason {
+	case "stop":
+		return "\x1b[32m" + line + "\x1b[0m"
+	case "error", "max_iterations":
+		return "\x1b[31m" + line + "\x1b[0m"
+	default:
+		return "\x1b[36m" + line + "\x1b[0m"
+	}
+}

core/agent/log_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 )
 
@@ -39,3 +40,60 @@ func TestJSONLoggerWritesTurnEvent(t *testing.T) {
 		t.Fatalf("reasoning tokens = %d, want 2", got.ReasoningTokens)
 	}
 }
+
+func TestTerminalLoggerWritesReadableTurnEvent(t *testing.T) {
+	var buf bytes.Buffer
+	logger := NewTerminalLogger(&buf, false)
+
+	logger.LogTurn(context.Background(), TurnEvent{
+		Duration:         "12ms",
+		Iterations:       2,
+		InputTokens:      20,
+		OutputTokens:     5,
+		CacheReadTokens:  3,
+		CacheWriteTokens: 1,
+		ReasoningTokens:  2,
+		Tools:            []string{"file_list", "file_read"},
+		Truncated:        true,
+		FinishReason:     "stop",
+	})
+
+	got := buf.String()
+	for _, want := range []string{
+		"turn stop",
+		"duration=12ms",
+		"iterations=2",
+		"tokens=20/5",
+		"cache=3/1",
+		"reasoning=2",
+		"tools=file_list,file_read",
+		"truncated=true",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("terminal log = %q, want %q", got, want)
+		}
+	}
+	if strings.Contains(got, "\x1b[") {
+		t.Fatalf("terminal log should not contain color escapes: %q", got)
+	}
+}
+
+func TestTerminalLoggerCanColorize(t *testing.T) {
+	var buf bytes.Buffer
+	logger := NewTerminalLogger(&buf, true)
+
+	logger.LogTurn(context.Background(), TurnEvent{
+		Duration:     "1ms",
+		Iterations:   1,
+		FinishReason: "error",
+		Error:        "failed",
+	})
+
+	got := buf.String()
+	if !strings.Contains(got, "\x1b[31m") || !strings.Contains(got, "\x1b[0m") {
+		t.Fatalf("terminal log = %q, want red color escapes", got)
+	}
+	if !strings.Contains(got, "error=failed") {
+		t.Fatalf("terminal log = %q, want error", got)
+	}
+}

docs/ROADMAP.md

@@ -93,7 +93,7 @@ A single agent you can talk to from the terminal, backed by a core harness that
 - [x] Structured JSON log line per turn: tools used, duration, loop iterations, finish reason, errors.
 - [x] Token and cache fields in turn logs.
 - [ ] Cost fields in turn logs.
-- [ ] Colored terminal logger for interactive sessions.
+- [x] Colored terminal logger for interactive sessions.
 - [ ] Cost estimation per provider and model.
 
 ### CLI