ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Contributing
Thanks for your interest in contributing to agtx! This guide will help you get started.
New here? Issues labeled good first issue are a great place to start β they're scoped, well-described, and a perfect way to get familiar with the codebase.
Getting Started
Prerequisites
- Rust 1.70+ (install)
- tmux (runtime dependency for agent sessions)
- git (runtime dependency for worktrees)
- gh CLI (optional, for PR operations)
Setup
git clone https://github.com/fynnfluegge/agtx
cd agtx
cargo build
cargo test --features test-mocks
Running Locally
# Run in any git repository
cd agtx && cargo run --manifest-path /path/to/agtx/Cargo.toml
# Or build and copy to PATH
cargo build --release
cp target/release/agtx ~/.local/bin/
Ways to Contribute
Bug Reports
Open an issue with:
- What you expected vs. what happened
- Steps to reproduce
- OS, terminal emulator, and agent CLI versions
Write a Plugin
Plugins are the easiest way to contribute. A single plugin.toml defines an entire workflow. See the plugin reference in the README.
Place your plugin in plugins/<name>/plugin.toml and open a PR. Check the existing plugins for examples:
plugins/void/plugin.tomlβ simplest possible pluginplugins/agtx/plugin.tomlβ full-featured with skills and promptsplugins/gsd/plugin.tomlβ cyclic workflow with preresearch
Add Agent Support
To add a new AI coding CLI:
- Add to
known_agents()insrc/agent/mod.rs - Add
build_interactive_command()match arm insrc/agent/mod.rs - Add agent-native skill directory in
agent_native_skill_dir()insrc/skills.rs - Add plugin command transform in
transform_plugin_command()insrc/skills.rs
Code Changes
- Fork the repository
- Create a feature branch:
git checkout -b my-feature - Make your changes
- Run tests:
cargo test --features test-mocks - Open a pull request against
main
Architecture Overview
See CLAUDE.md for the full architecture documentation, including:
- Module structure and key files
- Task workflow lifecycle
- Plugin system internals
- Agent integration patterns
- Testing patterns (mock traits, feature flags)
Key Directories
src/tui/ β TUI rendering and input handling
src/db/ β SQLite database (tasks, projects)
src/tmux/ β Tmux server management
src/git/ β Git worktree operations
src/agent/ β Agent detection, spawning, switching
src/mcp/ β MCP server for orchestrator
src/config/ β Configuration and plugin loading
plugins/ β Bundled workflow plugins
skills/ β Built-in skill files (embedded at compile time)
Testing
# Run all tests
cargo test --features test-mocks
# Run a specific test
cargo test --features test-mocks test_name
Tests use mock traits (TmuxOperations, GitOperations, AgentOperations) behind the test-mocks feature flag. Pure function tests don't need the feature flag.
Code Style
- Follow existing patterns in the codebase
- Use
anyhow::Resultfor fallible functions with.context()for error messages - Keep UI state in
AppState, drawing functions are static - Add tests for new functionality
License
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.