SynapsesOS
Internals

Contributing

This guide covers setting up a development environment and the workflow for contributing to Synapses.

Prerequisites

  • Go 1.23+ — Synapses is written in Go
  • Tree-sitter — Required for AST parsing
  • SQLite — Used for all persistence (usually available on macOS/Linux by default)

Getting Started

Terminal window
git clone https://github.com/SynapsesOS/synapses
cd synapses
make build

The binary is output to bin/synapses.

Building

Terminal window
make build

This compiles the main binary. The Makefile handles build flags and output paths.

Testing

Terminal window
make test

This runs go test ./internal/... ./cmd/synapses. Note that cmd/bicep_edge and cmd/debug_callsites are permanently excluded from test coverage — they are development utilities, not production code.

Linting

Terminal window
make lint

Uses standard Go linting tools. All code must pass lint before merge.

Code Style

  • Standard Go conventions apply — run gofmt before committing
  • No special style guide beyond what gofmt and the linter enforce
  • Keep functions focused and reasonably sized
  • Write table-driven tests where applicable

Key Directories

DirectoryWhat’s There
cmd/synapses/Main binary entry point
internal/graph/Graph engine — nodes, edges, BFS, PageRank
internal/mcp/MCP protocol server and tool handlers
internal/store/SQLite persistence layer
internal/parser/AST parsers (one file per language)
internal/watcher/File system watcher
internal/brain/LLM enrichment pipeline
internal/federation/Cross-project graph federation
internal/config/Configuration loading and defaults
bin/Compiled binaries (git-ignored)

PR Workflow

  1. Fork the repository
  2. Branch from main — use a descriptive branch name (e.g., fix-bfs-decay, add-kotlin-parser)
  3. Implement your changes
  4. Test — run make test and ensure all tests pass
  5. Lint — run make lint and fix any issues
  6. Commit with a clear message describing what and why
  7. Open a PR against main

What to Work On

Check the project’s ROADMAP.md and BACKLOG.md for planned work and open items. If you want to propose something new, open an issue first to discuss the approach.