75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# Agent Instructions
|
|
|
|
## Development Environment
|
|
This project uses [devenv](https://devenv.sh/) 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:
|
|
|
|
```bash
|
|
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
|