mirror of
https://github.com/block/goose.git
synced 2026-07-17 12:56:20 +02:00
Jack Amadeo
110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
# AGENTS Instructions
|
|
|
|
goose is an AI agent framework in Rust with CLI and Electron desktop interfaces.
|
|
|
|
## Setup
|
|
```bash
|
|
source bin/activate-hermit
|
|
cargo build
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Build
|
|
```bash
|
|
cargo build # debug
|
|
cargo build --release # release
|
|
just release-binary # release + openapi
|
|
```
|
|
|
|
### Test
|
|
```bash
|
|
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
|
|
```bash
|
|
cargo fmt
|
|
cargo clippy --all-targets -- -D warnings
|
|
```
|
|
|
|
### UI
|
|
```bash
|
|
just generate-openapi # after server changes
|
|
just run-ui # start desktop
|
|
cd ui/desktop && pnpm test # test UI
|
|
```
|
|
|
|
### Git
|
|
```bash
|
|
git commit -s # required for DCO sign-off
|
|
```
|
|
|
|
## Structure
|
|
```
|
|
crates/
|
|
├── goose # core logic
|
|
├── goose-acp # Agent Client Protocol
|
|
├── goose-acp-macros # ACP proc macros
|
|
├── goose-cli # CLI entry
|
|
├── goose-server # backend (binary: goosed)
|
|
├── goose-mcp # MCP extensions
|
|
├── goose-test # test utilities
|
|
└── goose-test-support # test helpers
|
|
|
|
evals/open-model-gym/ # benchmarking / evals
|
|
ui/desktop/ # Electron app
|
|
```
|
|
|
|
## Development Loop
|
|
```bash
|
|
# 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
|
|
# 4. [if server] just generate-openapi
|
|
```
|
|
|
|
## 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/
|
|
Server: Changes need just generate-openapi
|
|
|
|
## 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: Edit ui/desktop/openapi.json manually
|
|
Never: Edit Cargo.toml use cargo add
|
|
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
|
|
- Server: crates/goose-server/src/main.rs
|
|
- UI: ui/desktop/src/main.ts
|
|
- Agent: crates/goose/src/agents/agent.rs
|