agents: Instructions file for Codex

AI Agent Instructions (AGENTS.md)

Welcome to the agents repository! This file provides context, architectural guidelines, and development workflows for AI coding assistants (like Cursor, Copilot, or Claude Code) working on this codebase.

Project Overview

agents is a command-line tool for managing and interacting with AI agents locally. It supports creating specialized agents with specific system prompts, models, and tools. It also features Retrieval-Augmented Generation (RAG) capabilities using local files and an Audit Logging system to track agent conversations.

The project consists of two main components:

1. Go CLI: The core application, handling agent logic, tool execution, RAG indexing, and CLI interactions.
2. Audit Viewer: A lightweight web application to visualize and review conversation logs stored in DuckDB.

Tech Stack

Backend (CLI)

• Language: Go (1.25+)
• CLI Framework: Cobra (github.com/spf13/cobra)
• Database: DuckDB (github.com/duckdb/duckdb-go/v2) used for both RAG vector storage and Audit logging.
• Markdown Rendering: Glamour (github.com/charmbracelet/glamour)

Frontend (Audit Viewer)

• Runtime/Package Manager: Bun
• Framework: React 18 with TypeScript
• Database Driver: DuckDB (WASM/Node bindings)

Repository Structure

• cmd/: Cobra CLI commands (e.g., add.go, engage.go, rag.go).
• pkg/: Core application logic.
  • pkg/sdk/: The core agent SDK, handling interactions with the LLM (Gemini) and tool execution.
  • pkg/storage/: Database interactions (DuckDB) for RAG and Audit logs.
  • pkg/config/: Configuration parsing and management.
  • pkg/utils/: Helper functions.
• audit-viewer/: The React/Bun web application for viewing audit logs.
• examples/: Example configurations (e.g., PR reviewer agent).
• docs/: Additional documentation.

Development Workflow

Go CLI

The project uses a Makefile for common tasks. Always ensure your code passes these checks before considering a task complete.