Skip to content

Latest commit

 

History

History
99 lines (75 loc) · 3.14 KB

AGENTS.md

File metadata and controls

99 lines (75 loc) · 3.14 KB

Agent Instructions for gptme

This file provides agent-specific guidance for working on gptme. For general project information, see README.md and docs.

Git Workflow

  • Never push directly to master - always use branches and PRs
  • Branch naming: feat/, fix/, docs/, refactor/ prefixes
  • Commit format: Use Conventional Commits
    • feat: for new features (not just docs)
    • fix: for bug fixes
    • docs: for documentation only
    • refactor:, test:, chore: as appropriate
  • Stage files explicitly: Never use git add . or git commit -a
  • Create PRs: Use gh pr create after pushing branch

Code Style

  • Type hints: All functions must have type annotations
  • Formatting: ruff format and ruff check (run via pre-commit)
  • Type checking: mypy must pass
  • KISS: Keep it simple - avoid over-engineering
  • Small functions: Refactor deeply nested code into smaller units
  • Minimal mocking: Prefer integration tests over heavy mocking

Testing

Run tests before submitting PRs:

make test           # Fast tests (excludes slow/eval)
make test SLOW=1    # Include slow tests
make typecheck      # mypy
make lint           # ruff + other checks

Project Structure

Key directories:

  • gptme/ - Core library code
    • gptme/cli/ - CLI entry points
    • gptme/tools/ - Tool implementations
    • gptme/llm/ - LLM provider integrations
    • gptme/server/ - REST API server
  • tests/ - Test suite
  • docs/ - Sphinx documentation (RST + MD)
  • scripts/ - Build and utility scripts

Core vs gptme-contrib

We aim to keep gptme core small and focused. See docs/arewetiny.rst.

Belongs in core (gptme):

  • Essential tools (shell, save, patch, browser, vision)
  • Core infrastructure (chat loop, message handling, LLM providers)
  • Features needed by most users

Belongs in gptme-contrib:

  • Specialized tools (Twitter/X, Discord, email)
  • Experimental features
  • Integrations with specific services
  • Multi-agent patterns (consortium)

When in doubt, start in gptme-contrib. If widely adopted, consider upstreaming.

Performance

We track startup time and code size. See docs/arewetiny.rst.

CI benchmarks enforce startup thresholds.

Key Concepts

  • Tool: A function the assistant can execute (shell, save, patch, etc.)
  • ToolUse: Parsed representation of a tool invocation in a message
  • Message: A single message in the conversation
  • LogManager: Manages conversation history persistence
  • Step: One LLM generation + tool execution cycle
  • Turn: Complete user→assistant exchange (may include multiple steps)

See docs/glossary.md for full terminology.

Common Tasks

Adding a new tool

  1. Create gptme/tools/toolname.py
  2. Implement ToolSpec with execute() function
  3. Tools are auto-discovered - no manual registration needed
  4. Add tests in tests/test_tools_toolname.py

Running the server

uv run gptme-server --port 5000

Building docs

make docs