Skip to content

AGENT.md

Latest commit

 

History

History
74 lines (60 loc) · 3.05 KB

AGENT.md

File metadata and controls

74 lines (60 loc) · 3.05 KB

Agent Instructions

Development Environment

This project uses devenv for reproducible development environments with Nix.

Commands

  • devenv shell - Enter the development shell
  • devenv test - Run tests (currently runs git version check)
  • go build - Build Go project
  • go run main.go - Run the chat application
  • go test ./... - Run all Go tests
  • go test <package> - Run tests for specific package
  • go mod tidy - Download dependencies
  • hello - Custom script that greets from the development environment

Application Commands

  • go run chat.go - Simple chat interface with Claude
  • go run read.go - Chat with file reading capabilities
  • go run list_files.go - Chat with file listing and reading capabilities
  • go run bash_tool.go - Chat with file operations and bash command execution
  • go run edit_tool.go - Chat with full file operations (read, list, edit, bash)

Verbose Logging

All Go applications support a --verbose flag for detailed execution logging:

  • go run chat.go --verbose - Enable verbose logging for debugging
  • go run read.go --verbose - See detailed tool execution and API calls
  • go run edit_tool.go --verbose - Debug file operations and tool usage

Architecture

  • Environment: Nix-based development environment using devenv
  • Shell: Includes Git, Go toolchain, and custom greeting script
  • Structure: Chat application with terminal interface to Claude via Anthropic API

Code Style Guidelines

  • Follow Nix conventions for devenv.nix configuration
  • Use standard Git workflows
  • Development environment configuration should be reproducible

Troubleshooting

Verbose Logging

When debugging issues with the chat applications, use the --verbose flag to get detailed execution logs:

go run edit_tool.go --verbose

What verbose logging shows:

  • API calls to Claude (model, timing, success/failure)
  • Tool execution details (which tools are called, input parameters, results)
  • File operations (reading, writing, listing files with sizes/counts)
  • Bash command execution (commands run, output, errors)
  • Conversation flow (message processing, content blocks)
  • Error details with stack traces

Log output locations:

  • Verbose mode: Detailed logs go to stderr with timestamps and file locations
  • Normal mode: Only essential output goes to stdout

Common troubleshooting scenarios:

  • API failures: Check verbose logs for authentication errors or rate limits
  • Tool failures: See exactly which tool failed and why (file not found, permission errors)
  • Unexpected responses: View full conversation flow and Claude's reasoning
  • Performance issues: See API call timing and response sizes

Environment Issues

  • Ensure ANTHROPIC_API_KEY environment variable is set
  • Run devenv shell to ensure proper development environment
  • Use go mod tidy to ensure dependencies are installed

Notes

  • Requires ANTHROPIC_API_KEY environment variable to be set
  • Chat application provides a simple terminal interface to Claude
  • Use ctrl-c to quit the chat session