{"id":50708541,"url":"https://github.com/sincerema/sidetrail","last_synced_at":"2026-06-13T04:02:18.024Z","repository":{"id":363107030,"uuid":"1261016795","full_name":"SincereMa/sidetrail","owner":"SincereMa","description":"SideTrail is an open-source sidecar for AI-powered code tools that preserves long-lived project context outside the codebase. It records decisions, constraints, architecture drift, blast-radius dependencies, and difficulty signals so host agents can act with durable project memory instead of only the current source snapshot.","archived":false,"fork":false,"pushed_at":"2026-06-07T12:27:53.000Z","size":241,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T14:15:25.155Z","etag":null,"topics":["agent-integration","ai-assistant","knowledge-management","project-memory","sidecar","software-architecture"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SincereMa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-06T06:12:20.000Z","updated_at":"2026-06-07T12:27:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SincereMa/sidetrail","commit_stats":null,"previous_names":["sincerema/sidetrail"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/SincereMa/sidetrail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SincereMa%2Fsidetrail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SincereMa%2Fsidetrail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SincereMa%2Fsidetrail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SincereMa%2Fsidetrail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SincereMa","download_url":"https://codeload.github.com/SincereMa/sidetrail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SincereMa%2Fsidetrail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34110012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-integration","ai-assistant","knowledge-management","project-memory","sidecar","software-architecture"],"created_at":"2026-06-09T14:00:13.869Z","updated_at":"2026-06-09T14:00:15.573Z","avatar_url":"https://github.com/SincereMa.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SideTrail\n\n\u003e A sidecar that gives AI agents long-lived memory of the projects they work on — without modifying them.\n\nMainstream agents see the current state of a project. The reasoning\nthat produced that state is lost. The constraints that bind the\nproject live in the heads of the team, not in the code. The agent\ntreats every part of the project as equivalent, when in fact some\nparts are hard to change safely and some are easy. And when the agent\nedits a service, it has no reliable way to see which other services\ndepend on what it is about to change.\n\nSideTrail is a sidecar that records this missing context —\ndecisions, constraints, health signals, project state — and makes it\navailable to the host agent before it acts. It does not touch the\nhost agent. It does not replace it. It runs alongside it.\n\n## The five gaps\n\n1. **Reasoning trails for project evolution are lost between sessions.**\n\n   \u003e \"This area was adjusted three times. The first attempt changed\n   \u003e X because of Y. The second attempt found a side effect Z and\n   \u003e was rolled back to X. The current state is the result of the\n   \u003e third attempt, chosen specifically to avoid Z.\"\n\n2. **The blast radius of an edit is invisible across services, modules, and subprojects.**\n\n   The agent can see the file it is changing, but not the services,\n   modules, subprojects, or shared contracts that depend on that\n   file — statically, at runtime, or operationally. Local\n   correctness, global regression.\n\n3. **Project difficulty is uneven and shifts, but the agent has no read on it.**\n\n   Some modules are churn hotspots, some are bug clusters, some\n   have eroding test coverage, some depend on stale libraries. The\n   agent cannot prioritize, warn, slow down, or escalate review\n   where it matters.\n\n4. **Documented architecture drifts from actual architecture.**\n\n   \u003e \"The architecture diagram shows service A and service B as\n   \u003e cleanly separated. Service B has, for the last eight months,\n   \u003e been reading service A's primary database directly. Every new\n   \u003e feature in B assumes the read. Removing it is a multi-quarter\n   \u003e project, not a refactor.\"\n\n5. **Tribal constraints are nowhere the agent can read them.**\n\n   \u003e \"Don't change the code in `legacy/billing/` — there's a\n   \u003e compliance review pending.\"\n   \u003e\n   \u003e \"We use library Z despite its license because alternatives have\n   \u003e all been blocked by security.\"\n   \u003e\n   \u003e \"That migration is paused; do not touch the bridge code until\n   \u003e Q3.\"\n\nThe formal definition of each gap — kinds, statuses, sub-cases,\nsurface mapping, cross-cutting dimensions — is in\n[docs/scope.md](docs/scope.md). The non-negotiable principles that\nshape how we solve them are in [AGENTS.md](AGENTS.md).\n\n## How it works\n\nSideTrail is a **sidecar**, not a competing agent. It runs\nalongside the host agent (Claude Code, Cursor, Aider, …) and\nrecords long-lived context. It does not fork, patch, or inject into\nthe host.\n\nA few hard constraints shape the design:\n\n- **Non-intrusive.** Observe and record; never edit the host agent.\n- **Lightweight.** No heavy runtime, no bundled LLM calls the user\n  did not request.\n- **Cross-platform and cross-agent.** macOS, Linux, Windows; one\n  binary, one config; adding support for a new host agent is a\n  localized change.\n- **Simple configuration.** Near-zero config to get value;\n  everything else opt-in.\n\nThe full principle set lives in [AGENTS.md](AGENTS.md).\n\n## Status\n\nEarly development. The v0 CLI surface is in place; tagged builds\nare published as GitHub releases. The problems the project exists\nto address are recorded in [docs/scope.md](docs/scope.md); the\narchitectural decisions that follow from them live in\n[docs/decisions/](docs/decisions/).\n\n## Install\n\nThe fastest path is a one-liner. It downloads the latest release\nfor your OS and architecture, verifies the SHA-256, and drops the\n `sidetrail` binary on disk.\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/SincereMa/sidetrail/main/scripts/install.sh | sh\n```\n\nOn Windows, from PowerShell:\n\n```powershell\niwr https://raw.githubusercontent.com/SincereMa/sidetrail/main/scripts/install.ps1 -useb | iex\n```\n\nBoth scripts accept flags. See `scripts/install.sh --help` or\n`Get-Help ./scripts/install.ps1` for options. The binary lands in\n`~/.local/bin` (or `%USERPROFILE%\\bin` on Windows) by default; add\nthat directory to `PATH` if it is not already.\n\nFor a pinned version, set `SIDETRAIL_VERSION=v0.1.0` (or pass\n`--version` / `-Version`). For a custom install location, set\n`SIDETRAIL_INSTALL_DIR` (or pass `--dir` / `-InstallDir`).\n\nIf you prefer to install manually, download a release archive from\nthe [GitHub releases page](https://github.com/SincereMa/sidetrail/releases),\nverify it against the matching `*_checksums.txt`, and place the\n `sidetrail` binary anywhere on `PATH`.\n\n## Project layout\n\n| Path | Purpose |\n| --- | --- |\n| `AGENTS.md` | Mission, principles, and pointers for contributors and host agents. |\n| `LICENSE` | MIT license terms. |\n| `CODE_OF_CONDUCT.md` | Community expectations. |\n| `CONTRIBUTING.md` | How to file issues and submit changes. |\n| `docs/scope.md` | The problems SideTrail exists to address; the input to subsequent ADRs. |\n| `docs/decisions/` | Architectural decision records. |\n| `docs/agents/` | Per-host-agent adapter specifications. |\n| `ROADMAP.md` | Implementation status, outstanding tasks, and next milestones. |\n\n## CLI surface\n\nThe  `sidetrail` binary is a read-dominant command. Most calls ask a\nquestion; a few write a record. The `.sidetrail/` store is discovered\nby walking upward from the current working directory unless\n`--root` points elsewhere. The CLI surface has thirteen subcommands:\n\n| Command | Purpose |\n| --- | --- |\n| `sidetrail add \u003cfile\u003e` | Validate a record file and add it to the store. |\n| `sidetrail get \u003cid\u003e [--human]` | Fetch a record by id (exact, then prefix). |\n| `sidetrail list [--kind K] [--limit N] [--json]` | List records, newest first. |\n| `sidetrail ask --scope \u003cs\u003e [--kind] [--tag] [--limit] [--json]` | Query records whose scope matches a pattern. |\n| `sidetrail context --file \u003cpath\u003e [--radius N] [--limit] [--json]` | Aggregate records relevant to a file path. |\n| `sidetrail verify \u003cid\u003e` | Refresh a record's `last_verified_at`. |\n| `sidetrail supersede \u003cold-id\u003e --new \u003cfile\u003e` | Mark a record superseded and add a replacement. |\n| `sidetrail init [--root \u003cproject\u003e] [--no-write]` | Seed a `.sidetrail/` store from existing project docs. |\n| `sidetrail promote [\u003cid\u003e...] [--all]` | Promote seed records from `_seed/` to the active store. |\n| `sidetrail draft \u003ckind\u003e --subject \u003cs\u003e` | Create a draft record for human review in `_draft/`. |\n| `sidetrail status \u003cid\u003e \u003carchived\\|hidden\\|active\u003e` | Transition a record's status. |\n| `sidetrail validate \u003cfile\u003e... [--json]` | Validate record files against the schema. |\n| `sidetrail health [--json] [--stale-days N]` | Report project health signals and stale records. |\n\nThe first host-agent integration point is `sidetrail context`: point\nit at the file the agent is about to edit, and it returns the\nrecords the team has filed about that file and its enclosing\nscopes.\n\nAdapter guides for specific host agents live in\n[docs/agents/](docs/agents/). The first is for\n[OpenCode](docs/agents/opencode.md), a model-agnostic coding\nagent.\n\n`sidetrail init` is the cold-start path. It scans the canonical\nproject paths and writes scrape-derived candidate records to\n`.sidetrail/_seed/`. Skipping init is valid; the sidecar is usable\nfrom empty.\n\n## Contributing\n\nIssues and pull requests are welcome. Please read\n[CONTRIBUTING.md](./CONTRIBUTING.md) and\n[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) first.\n\n## License\n\n[MIT](./LICENSE). Copyright (c) 2026 SideTrail Authors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsincerema%2Fsidetrail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsincerema%2Fsidetrail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsincerema%2Fsidetrail/lists"}