---
title: Contributing
parent: Development
nav_order: 1
---

# Contributing

Thanks for your interest in contributing to agent-dashboard.

---

## Prerequisites

- [Go 1.26+](https://go.dev/dl/)
- [tmux](https://github.com/tmux/tmux)
- [Node.js 18+](https://nodejs.org/) (for the Claude Code adapter)

## Setup

```bash
git clone https://github.com/bjornjee/agent-dashboard
cd agent-dashboard
make build
make test
```

## Make targets

```bash
make build          # Build TUI binary (version from git tag or VERSION file)
make build-web      # Build web server binary
make fmt            # Auto-format Go source files
make vet            # Check formatting + go vet
make test           # Run all tests (vets first, CGO disabled for macOS)
make test-race      # Run tests with race detector (CI only)
make install        # Build and install binary from source
make uninstall      # Remove binary and state directory
make install-web    # Install web server binary
make web            # Run web server locally on port 8390
make seed           # Create fake agent state for testing
make clean          # Remove build artifacts and state
make help           # Show all available targets
```

## Testing

Tests run with `CGO_ENABLED=0` by default to avoid [macOS AMFI kills](../learnings/#macos-amfi-kills-unsigned-test-binaries). The race detector is enabled separately in CI via `make test-race`.

All tests use mocks — never real subprocesses. Mocks are generated by [mockery](https://github.com/vektra/mockery) from `.mockery.yaml`.

## Submitting changes

1. Fork the repo and create a feature branch from `main`
2. Make your changes and ensure `make test` passes
3. Use [conventional commits](https://www.conventionalcommits.org/) for commit messages
4. Open a pull request against `main`

## Versioning

The project uses semantic versioning managed by [release-please](https://github.com/googleapis/release-please). The version is resolved from the latest git tag (stripping the `v` prefix), falling back to the `VERSION` file. It is injected into the binary at build time via Go's `-ldflags -X` mechanism.

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/bjornjee/agent-dashboard/blob/main/LICENSE).
