tkmind_go/AGENTS.md

AGENTS Instructions

goose is an AI agent framework in Rust with CLI and Electron desktop interfaces.

Setup

source bin/activate-hermit
cargo build

Commands

Build

cargo build                   # debug
cargo build --release         # release  
just release-binary           # release binary

Test

cargo test                   # all tests
cargo test -p goose          # specific crate
cargo test --package goose --test mcp_integration_test
just record-mcp-tests        # record MCP

Lint/Format

cargo fmt
cargo clippy --all-targets -- -D warnings

UI

just run-ui                  # start desktop
cd ui/desktop && pnpm run typecheck
cd ui/desktop && pnpm test   # test UI

Structure

crates/
├── goose              # core logic
├── goose-acp-macros   # ACP proc macros
├── goose-cli          # CLI entry
├── goose-mcp          # MCP extensions
├── goose-test         # test utilities
└── goose-test-support # test helpers

ui/desktop/            # Electron app

Development Loop

# 1. source bin/activate-hermit
# 2. Make changes
# 3. cargo fmt

Run these only if the user has asked you to build/test your changes:

# 1. cargo build
# 2. cargo test -p <crate>
# 3. cargo clippy --all-targets -- -D warnings

Rules

• Test: Prefer tests/ folder, e.g. crates/goose/tests/
• Test: When adding features, update goose-self-test.yaml, rebuild, then run goose run --recipe goose-self-test.yaml to validate
• Error: Use anyhow::Result
• Provider: Implement Provider trait see providers/base.rs
• MCP: Extensions in crates/goose-mcp/
• UI Desktop: Use ACP SDK types or local src/types/* types. Do not import generated OpenAPI types/client code from ui/desktop/src/api

Code Quality

• Comments: Write self-documenting code - prefer clear names over comments
• Comments: Never add comments that restate what code does
• Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
• Simplicity: Don't make things optional that don't need to be - the compiler will enforce
• Simplicity: Booleans should default to false, not be optional
• Errors: Don't add error context that doesn't add useful information (e.g., .context("Failed to X") when error already says it failed)
• Simplicity: Avoid overly defensive code - trust Rust's type system
• Logging: Clean up existing logs, don't add more unless for errors or security events

Never

• Never: Recreate ui/desktop/src/api or add @hey-api/openapi-ts to ui/desktop
• Cargo.toml: For human-authored dependency changes, use cargo add instead of manually editing dependency entries unless there is a specific reason not to.
• Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep Cargo.lock consistent.
• Never: Skip cargo fmt
• Never: Merge without running clippy
• Never: Comment self-evident operations (// Initialize, // Return result), getters/setters, constructors, or standard Rust idioms

Entry Points

• CLI: crates/goose-cli/src/main.rs
• UI: ui/desktop/src/main.ts
• Agent: crates/goose/src/agents/agent.rs