\n\n# DevTrack\n\n**Never write a standup again.**\n\n*You commit. Tickets update, EOD reports write themselves — silently, in your voice, entirely on your machine.*\n\n`devtrack` — a single Go binary. Local-first. Offline by default.\n\n[](https://github.com/sraj0501/Devtrack_/releases/latest)\n[](https://github.com/sraj0501/Devtrack_/releases/latest)\n[](TERMS.md)\n\n\n\n
\n\n---\n\n## The 30-second pitch\n\nYou write code. DevTrack handles the rest.\n\nA background daemon watches your commits and infers everything around them — which ticket you're on (from the branch name), what you did today, what the standup should say. It drafts the ticket comment and the EOD report **in your writing voice**, learned from your own git history. Your only obligation: name branches with ticket IDs.\n\n**Nothing is sent behind your back.** Every outbound action — a Jira comment, a ticket transition, an email — is *staged* in a review queue first. You approve it, or you let it earn auto-approve over time. The daemon never prompts you, never blocks a commit, and never interrupts.\n\n### And it's the memory your AI agents lack\n\n> **Available since v3.1.0:** Phase 9 onboarding and the local, read-only MCP server ship in the\n> latest public release, v3.1.1. Five native MCPB bundles are available for Windows, macOS, and Linux.\n\nCoding agents are session-based: they exist while invoked, then forget. DevTrack is always on. One command —\n\n```bash\ndevtrack mcp setup\n```\n\n— and Claude Code knows your active ticket, today's commits, your pending queue, and how you write. Nothing else runs at 6pm, groups the day's commits by ticket, and has the EOD ready before you ask.\n\n### Trust\n\nLocal Ollama by default; SQLite on disk. **The default daily path stays on your machine.** If you\nconfigure a PM system, email/chat delivery, an external server, or a cloud LLM, DevTrack sends only\nthe payload needed for that enabled operation. Anonymous usage telemetry is **opt-in** and off unless\nyou run `devtrack telemetry on`.\n\n---\n\n## Ten-minute quickstart\n\nThe latest public release is **v3.1.1**. Download the matching platform asset from\n[GitHub Releases](https://github.com/sraj0501/Devtrack_/releases/tag/v3.1.1), or build from source:\n\n```bash\ngit clone --branch main --single-branch https://github.com/sraj0501/Devtrack_.git\ncd Devtrack_/devtrack_client\ngo build -o devtrack .\nsudo install -m 0755 devtrack /usr/local/bin/devtrack\n```\n\nVerify that this is an MCP-capable build, then run setup from the Git repository you want DevTrack\nto watch. Choose `none` when asked for a PM integration if you only want to try the local path.\nManaged mode requires a PostgreSQL URL for the Python service; Ollama remains the default LLM and\ncan finish preparing in the background.\n\n```bash\ndevtrack mcp status # must report six registered tools\ncd /path/to/the/repo/to/watch\ndevtrack setup\n```\n\n### Minute 2: local context, no Python or model required\n\nThe Go binary and local SQLite database are ready as soon as setup finishes. Wire the current\nrepository into Claude Code, then exercise the same MCP server locally:\n\n```bash\ndevtrack mcp setup\ndevtrack mcp test\n```\n\nReload Claude Code after `mcp setup`. Its DevTrack tools can now read the active ticket, today's\ncommits, pending actions, voice profile, ticket context, and a template EOD summary. The MCP server\nruns on demand over stdio; it does not need a background Python process.\n\n### Minutes 3–10: start the silent worker\n\n```bash\ndevtrack start\ndevtrack status\ndevtrack doctor\n```\n\n`status` and `doctor` report background Python, PostgreSQL, and LLM readiness without blocking Git\nmonitoring or MCP. Once the AI server reports ready, create a normal ticket-named branch and commit:\n\n```bash\ngit switch -c feature/AUTH-42-refresh-token\ngit commit -m \"fix auth redirect\"\n\ndevtrack logs # confirm the commit and ticket were detected\ndevtrack queue # review local pending actions and confidence\ndevtrack eod # generate a narrative; stages it before any delivery\n```\n\nDo not run `queue approve` while evaluating the no-send path. With the workspace PM integration set\nto `none` and no `--email` argument, the walkthrough uses no PM credentials and has no external\ndestination. For a disposable, recorder-friendly version that verifies actual log output instead of\nusing a canned transcript, see the [demo storyboard](docs/DEMO_STORYBOARD.md).\n\n### What is ready when?\n\n| Capability | Available before AI readiness | Needs the managed/external Python service |\n|---|---:|---:|\n| Git monitoring, ticket extraction, local SQLite | Yes | No |\n| MCP setup, self-test, and local context tools | Yes | No |\n| Queue inspection and correction for local actions | Yes | No |\n| Voice-aware ticket-comment generation | No | Yes |\n| `devtrack eod` generated narrative and staging | No | Yes |\n\nThe Python service and model preparation are background work. If they are not ready by minute ten,\nkeep coding and check `devtrack doctor`; the Go-native path remains usable and commits are not\nblocked.\n\n### Update an existing installation\n\n```bash\ndevtrack upgrade\n```\n\n`devtrack upgrade` installs the latest public release, including the Phase 9 onboarding and MCP\ncommands introduced in v3.1.0.\n\nThe daemon mines enabled local repositories in Managed mode and builds the voice profile once the\nlocal AI server is reachable. `devtrack status` and `devtrack doctor` show the persistent result and\nsuggest `devtrack work report` when the profile is ready.\n\nSetup also checks Ollama's local model inventory. An existing generation model is used immediately\nwithout another pull. If no usable local model is ready and an OpenAI or Anthropic key is already in\nthe environment, setup offers that key as a temporary fallback while Ollama downloads; Ollama stays\nprimary and automatically takes over when the local model becomes available.\n\n> **Updating?** Run `devtrack upgrade` to download and install the latest binary automatically (fetched from GitHub Releases; supports Linux/macOS and Windows).\n> If the binary is in a root-owned location (e.g. `/usr/local/bin`), run `sudo devtrack upgrade` instead. On Windows, re-run as Administrator if a permission error occurs.\n> Versioned migrations are applied automatically and the daemon is restarted after a successful upgrade.\n\n> `devtrack setup` writes a complete environment file under the DevTrack XDG data directory and registers it in `~/.devtrack/devtrack.conf`. Visible runtime defaults are editable; valid shell, CI, and secret-manager overrides still take precedence.\n\n> Full walkthrough and guides: **[devtrack.cloud](https://devtrack.cloud)**\n\n#### Moving to a new machine?\n\nProject memory and agent logs are committed to the repo (`.claude/memory/`, `Data/agent_logs/`). After cloning, wire up Claude Code's memory system with one command:\n\n```bash\n# Replace with the absolute repo path, slashes replaced by hyphens\n# e.g. repo at /home/sraj/devtrack → -home-sraj-devtrack\nmkdir -p ~/.claude/projects//\nln -s $(pwd)/.claude/memory ~/.claude/projects//memory\n```\n\nClaude Code will then read and write memory directly to the repo, keeping it in sync with git.\n\n---\n\n## The core loop\n\nThe daemon is **silent**. It does not prompt, block, or interrupt — it observes and stages.\n\n```\nYou: git checkout -b feat/AUTH-42-refresh-token\nYou: git commit -m \"fix auth redirect\"\n │\n ▼\n DevTrack observes (background — you are not interrupted)\n │\n ├── infers ticket AUTH-42 from the branch name\n ├── drafts a ticket comment in your voice\n └── STAGES it — nothing is sent yet\n │\n ▼\n devtrack queue # review what's waiting\n devtrack queue approve \n │\n At 6pm: today's commits, grouped by ticket\n ▼\n devtrack eod # the standup, already written\n```\n\nReview the queue whenever you like — it waits for you:\n\n```bash\ndevtrack queue # what DevTrack wants to send\ndevtrack queue approve # send it\ndevtrack queue reject # discard it\ndevtrack eod # preview today's EOD report\n```\n\n### Optional: AI-enhanced commits\n\nSeparately, `devtrack git commit` is an **interactive** wrapper that refines your commit message with AI, offers a ticket picker, and can log time. It is opt-in and never part of the silent daemon path:\n\n```bash\neval \"$(devtrack shell-init)\" # add to ~/.zshrc or ~/.bashrc — done once\ndevtrack enable-git # opt this repo in\n```\n\nAfter that, `git commit` routes through DevTrack for monitored repos. Everything else (`git push`, `git pull`, `git status`) goes straight to real git, unmodified. Escape hatch: `GIT_NO_DEVTRACK=1 git commit -m \"skip\"`.\n\n> AI commit enhancement is only active when the daemon is running. If you stop it, `git commit` passes through with zero delay and no errors.\n\n---\n\n## What it connects to\n\n| Integration | What DevTrack does |\n|-------------|-------------------|\n| **Azure DevOps** | Post commit comments, transition work item states, create missing items; PR approval detection via ADO Pull Requests API (real `IsPRApproved`, vote ≥ 10) |\n| **GitHub** | Comment on issues/PRs, sync recent activity, alert on review requests |\n| **GitLab** | Comment on issues; list, view, create, and sync issues through the Go connector |\n| **Jira** | Server-side webhook and PM support; Go-client connector parity is part of the staged rollout |\n| **Microsoft Teams** | Learn your communication style for personalized AI output |\n| **Outlook / MS Graph** | Send EOD reports by email |\n| **Telegram** | Go-native daemon control, logs, queue review/corrections, and notifications |\n| **Slack** | Outbound alert notifications through an incoming webhook |\n| **Ollama / OpenAI / Anthropic / Groq** | AI commit messages, reports, conflict resolution, git-sage agent |\n\n---\n\n## Key features\n\n### The pending-actions queue — nothing is sent without review\n\nEvery outbound action DevTrack wants to take is **staged first**, never fired blind. This is the trust primitive: one reviewable queue for everything that would otherwise write to your Jira, GitHub, or inbox.\n\n```bash\ndevtrack queue # list pending actions (default)\ndevtrack queue --all # include recently posted/rejected\ndevtrack queue status # one-line summary: pending / posted today / rejected today\ndevtrack queue approve # send it now\ndevtrack queue reject # discard — will not post\ndevtrack queue edit # fix the payload before it goes\n```\n\nEach action carries a confidence score. As you approve a given action type repeatedly, it can earn auto-approve — so DevTrack gets quieter the more you trust it, not louder.\n\n### End-of-day report — the standup, already written\n\n```bash\ndevtrack eod # generate today's report\ndevtrack eod show # print the most recent narrative\ndevtrack eod status # is one staged?\n```\n\nGroups the day's commits by ticket and writes the narrative in your voice. It is staged in the queue like anything else — review it, then send.\n\n### Multi-repo monitoring\n\n```yaml\n# workspaces.yaml\nworkspaces:\n - name: work-api\n path: ~/work/api\n pm_platform: azure\n pm_assignee: jane@example.com\n pm_iteration_path: \"MyProject\\\\Sprint 5\"\n pm_area_path: \"MyProject\\\\Backend\"\n - name: oss-lib\n path: ~/oss/my-lib\n pm_platform: github\n pm_milestone: 3\n # Dual-platform: same repo tracked in GitHub (code) + Azure DevOps (PM)\n - name: my-api-github\n path: ~/work/my-api\n pm_platform: github\n pm_org: acme-corp\n pm_username: sraj0501\n skip_issues: true # code-only: excluded from devtrack issues + ticket sync\n - name: my-api-ado\n path: ~/work/my-api\n pm_platform: azure\n pm_org: acme-corp\n pm_username: jane@acme.com\n```\n\nPer-workspace PM overrides (`pm_assignee`, `pm_iteration_path`, `pm_area_path`, `pm_milestone`) are applied when DevTrack creates work items or issues for that repo — Azure uses `assigned_to`/`area_path`/`iteration_path`, GitHub/GitLab use `assignees` and `milestone`. Omit any field to use the global default.\n\n`skip_issues: true` marks a workspace as code-only — it is excluded from `devtrack issues`, ticket sync, and the commit-time ticket picker. Use this when the same repo is tracked in two PM platforms (e.g. GitHub for code review, Azure DevOps for sprint planning) to prevent duplicate ticket lists.\n\n```bash\ndevtrack workspace list\ndevtrack workspace add my-project ~/code/project --pm github\ndevtrack workspace install-hooks # push post-commit hooks to all enabled workspaces\n```\n\n> **Empty repositories**: If a monitored workspace has no commits yet, the daemon watches the folder silently and begins triggering normally once the first commit arrives — no log spam or errors during the empty-repo period.\n\n### Work session tracking\n\n```bash\ndevtrack work start AUTH-42 # start timing a ticket\ndevtrack work stop # auto-measures duration\ndevtrack work report # EOD narrative in terminal\ndevtrack work report --email me@org.com\n```\n\nEvery `git commit` while a session is active automatically attaches its hash — no manual logging.\n\n### git-sage — local LLM git agent\n\n\n\n```bash\ndevtrack sage do \"squash my last 5 commits\"\ndevtrack sage ask \"how do I rebase onto main?\"\n```\n\nRuns an agentic loop: plans operations, executes them, reads output, handles failures with rollback, only asks when genuinely ambiguous. Session approval dialog (auto / review / suggest-only), step history, and interactive undo built in.\n\n### Personalized AI (\"Talk Like You\")\n\n```bash\ndevtrack enable-learning # opt in\ndevtrack learning-sync # mine your git history\ndevtrack show-profile # view your inferred writing style\ndevtrack test-response \"Completed auth module\"\n```\n\nLearns your writing voice from **your own git history** — local, automatic, no external service. It combines a style profile with ChromaDB RAG (real examples of how you write) to personalize every commit message, ticket comment, and report the system generates.\n\nOn a fresh Managed installation, the daemon automatically seeds Tier 0 voice data from enabled local Git\nworkspaces and generates the first profile in the background. Completion is saved locally in\n`first-run-profile.json`; no PM action is sent and daemon startup never waits for the profile.\n\nMicrosoft Teams is an **optional** extra signal (`TEAMS_ENABLED`), not a requirement — the local git-history path is the default and works entirely offline.\n\n### Ticket alerter\n\n```bash\ndevtrack alerts # unread notifications (last 24 h)\ndevtrack alerts --all\ndevtrack alerts --clear\n```\n\nThe Go-native background poller watches **GitHub** and **Azure DevOps** for assigned work, comments,\nreview requests, and status changes. It can deliver terminal, OS, Telegram, and Slack-webhook\nnotifications.\n\n- **GitHub**: Issue/PR assigned, review requested, comment on involved issue\n- **Azure DevOps**: Work item assigned, comment added, state changed\nThe poller is **Go-native** and runs inside the daemon — no Python subprocess, no MongoDB. Alert state (`last_checked` per source) and notifications persist to **SQLite**, so poll continuity survives daemon restarts.\n\n### Telegram bot — remote control from your phone\n\nControl the daemon and supervise queued work without opening a terminal:\n\n```\n/status | /logs | /health | /trigger\n/pause | /resume | /stop | /restart | /reload\n/commits\n/queue\n/approve | /reject | /edit \n```\n\nSee [Telegram Bot setup guide](docs/TELEGRAM_BOT.md) for full configuration.\n\n### Auto-start at login\n\nOne command installs the right service for your OS — no manual plist or unit file editing:\n\n```bash\ndevtrack autostart-install # macOS → launchd LaunchAgent\n # Linux/systemd → ~/.config/systemd/user/devtrack.service\n # WSL without systemd → shell profile block\ndevtrack autostart-status # show current auto-start status\ndevtrack autostart-uninstall # remove auto-start\n```\n\nRelevant DevTrack runtime variables from the current environment are baked into the service definition\nat install time so the daemon starts correctly even in a login session without a shell profile.\nRe-run `autostart-install` after changing the environment file.\n\nThe daemon enforces a single running instance using an OS-level file lock (`Data/devtrack.lock`). On Windows this is a mandatory lock; on Unix a cooperative flock. Attempting to start a second instance prints a clear error and exits immediately rather than running in parallel and corrupting shared state.\n\n### Interactive setup wizard (`devtrack setup`)\n\nWalks through every required setting interactively and writes the result for you:\n\n```bash\ndevtrack setup\n```\n\nWhat it does:\n- Checks Git is installed before proceeding\n- Prompts for operating mode (Managed / External) and LLM provider credentials\n- Reuses an installed generation-capable Ollama model without downloading a prescribed model\n- When Ollama still needs a model, can retain an already-present OpenAI/Anthropic key as an explicit\n temporary fallback; key values are never displayed and declining keeps setup local-only\n- In Managed mode, starts the optional Python checkout, `uv sync`, and any needed local Ollama model\n pull in a detached worker; setup does not wait for them\n- Generates the registered XDG environment file with visible runtime defaults and an auto-generated `ADMIN_SECRET_KEY`\n- In Managed mode, writes and validates the required PostgreSQL connection configuration\n- Creates the `~/.devtrack/` configuration directory and writes `workspaces.yaml` there\n- Writes `WORKSPACES_FILE` into the generated environment file, pointing at the workspace file\n- Registers shell integration automatically in `.bashrc` or `.zshrc` on Unix and the PowerShell\n profile on Windows\n- Writes `~/.devtrack/devtrack.conf` pointing at the generated environment file\n\nAfter `devtrack setup` completes, run `devtrack start` — no manual `source .env` needed. Git\nmonitoring, local SQLite, scheduling, and MCP are ready while the optional AI server finishes in the\nbackground. Use `devtrack doctor` or `devtrack status` for progress; retry a failed bootstrap with\n`devtrack doctor --repair`.\n\n### Automatic `.env` loading\n\nThe daemon automatically finds and loads `.env` at startup. Resolution order:\n\n1. `DEVTRACK_ENV_FILE` environment variable (explicit path)\n2. Path recorded in `~/.devtrack/devtrack.conf` (written by `devtrack setup`)\n3. `.env` file next to the `devtrack` binary\n\nYou no longer need to manually `source .env` before `devtrack start` for most setups. The env-first rule still applies for `devtrack autostart-install` — run it after `devtrack setup` so the service bakes the correct variables.\n\n### Uninstall (`devtrack uninstall`)\n\n```bash\ndevtrack uninstall # confirm, then remove DevTrack and its data\ndevtrack uninstall --keep-data # remove DevTrack but preserve the data directory\ndevtrack uninstall --yes # skip the confirmation prompt\n```\n\nThe uninstall command asks once for confirmation unless `--yes` is supplied. It:\n- Stops the running daemon (if active)\n- Removes the autostart entry (launchd on macOS, systemd on Linux, Task Scheduler on Windows)\n- Deletes the configured DevTrack data home, including managed-server files, unless `--keep-data` is supplied\n- Removes the `devtrack` binary from `PATH`\n\nThe command prints the resolved targets before confirmation. There is no `--dry-run` flag.\n\n### Self-update (`devtrack upgrade`)\n\n```bash\ndevtrack upgrade # download and install the latest release binary\nsudo devtrack upgrade # use when the binary is in a root-owned directory (e.g. /usr/local/bin)\n```\n\nWhat happens on upgrade:\n1. Downloads the latest binary for your OS/arch from **GitHub Releases** (`sraj0501/Devtrack_`) — Linux/macOS use `.tar.gz`; Windows uses a direct `.exe`\n2. Applies all versioned migrations that have not yet run (schema changes, config file moves, etc.)\n3. Auto-restarts the daemon so the new binary takes effect immediately\n4. On Unix: falls back to `sudo cp` automatically if the target directory is root-owned and the command wasn't run as root\n5. On Windows: if a permission error occurs, a message is printed asking you to re-run the command as Administrator\n\n### Post-commit hooks for all workspaces\n\n```bash\ndevtrack workspace install-hooks # install post-commit hook in every enabled workspace\n```\n\nNormally DevTrack installs hooks when the daemon starts. Use this command to push hooks to all workspaces at once — useful after adding new repos to `workspaces.yaml`.\n\n### Webhook + Trigger server (HTTP mode)\n\nThe Go daemon spawns `backend.webhook_server` as a subprocess in the default managed mode. In external/Docker mode the server runs separately and the Go daemon connects to it over HTTPS. Either way the same FastAPI server handles both:\n\n- **Inbound webhooks** from Azure DevOps, GitHub, GitLab, and Jira at `/webhooks/`\n- **Outbound triggers** from the Go daemon at `/trigger/commit` and `/trigger/timer`\n\n```bash\n# external/Docker mode only — managed mode starts this automatically\ncd devtrack_server && uv run python -m backend.webhook_server\n```\n\nAll trigger endpoints require the `X-DevTrack-API-Key` header (set `DEVTRACK_API_KEY` in `.env`). Webhook signature verification uses source-specific secrets (`AZURE_WEBHOOK_SECRET`, `GITHUB_WEBHOOK_SECRET`, etc.). GitLab webhooks are registered automatically at startup when `GITLAB_WEBHOOK_URL` is configured.\n\nThe stable request and response shapes, authentication rules, and matching Go/Python contract tests\nare documented in [the HTTP API contract](docs/HTTP_API.md).\n\n### Claude Code / MCP Integration (Phase 8)\n\nDevTrack exposes a Model Context Protocol (MCP) server so Claude Code automatically knows your active ticket, commit voice, and pending queue — no manual context-setting needed.\n\n- **`devtrack mcp`** — starts the MCP server in stdio mode (the transport Claude Code uses)\n- **`devtrack mcp serve --database PATH`** — starts it against an explicitly selected `devtrack.db`\n (used by packaged MCPB installs)\n- **`devtrack mcp setup`** — writes `.mcp.json` in the current directory so Claude Code discovers the server automatically on next launch\n- **`devtrack mcp status`** — shows the registered tools and server info\n- **`devtrack mcp test`** — runs an in-process smoke test without starting a full server\n- Six SQLite-backed tools: `get_active_context`, `get_today_commits`, `get_pending_actions`,\n `get_voice_profile`, `get_ticket_context`, `get_eod_summary`. Each declares a title and read-only,\n non-destructive, idempotent safety annotations.\n- The stdio handshake negotiates finalized MCP versions through `2025-11-25`, retaining older-client\n compatibility. The newer `2026-07-28` per-request protocol is not supported yet.\n- Reproducible MCPB 0.3 bundles ship for Windows amd64, macOS amd64/arm64, and Linux amd64/arm64.\n During bundle installation, select the `devtrack.db` created by `devtrack setup`. Published\n bundle hashes are recorded in the release's `checksums.txt` and official MCP Registry metadata.\n- `Dockerfile.mcp` is the minimal Linux stdio image used for directory build/introspection checks.\n It creates disposable SQLite state and is separate from `devtrack_server/Dockerfile`, which runs\n the optional Python HTTP backend. The root `.dockerignore` keeps local credentials and runtime\n data out of that build context.\n\n```bash\n# One-time setup — run from your repo root\ndevtrack mcp setup # writes .mcp.json\n# Restart Claude Code — it will connect automatically via stdio\ndevtrack mcp status # verify tools are registered\ndevtrack mcp test # smoke-test the server in-process\n```\n\nSource: `devtrack_client/internal/mcp/` (server core) and `devtrack_client/mcp_cmd.go` (CLI).\n\n### Development-agent playbooks\n\nThe repository retains five historical Claude role definitions under\n[`.claude/agents/_archive/`](.claude/agents/_archive/) and keeps the current role, memory, and\nauthorization contract in\n[`.claude/memory/project_local_agents.md`](.claude/memory/project_local_agents.md). These are\nproject-maintenance assets, not `devtrack` CLI commands, and the archived files are not advertised\nas automatically installed Claude slash commands. A contributor's Codex or agent environment may\ninstall adapters for the same roles separately.\n\n| Role | Responsibility |\n|------|----------------|\n| **project-vision** | Break plans into board tasks and enforce vision and authorization boundaries |\n| **devtrack-engineer** | Implement an approved `TASK-NNN` on a task branch and record engineering evidence |\n| **git-agent** | Perform explicitly authorized Git plumbing without expanding the requested scope |\n| **memory-compactor** | Reconcile durable project memory without discarding still-relevant decisions |\n| **post-generator** | Turn engineer-log evidence into held dev.to, Hacker News, and LinkedIn drafts under `Data/agent_logs/posts/` |\n\nThe documentation-maintenance workflow is checked in at\n[`.claude/commands/docu-agent.md`](.claude/commands/docu-agent.md); how a contributor invokes it\ndepends on their local agent environment. The planning and\nengineering roles use `Data/agent_logs/project_board.md` as their durable contract, while verified\nimplementation history is recorded in `Data/agent_logs/engineer_log.md`. Role names alone do not\nauthorize commits, pushes, PR operations, releases, publication, or deployment.\n\n### Anonymous telemetry — opt-in, off by default\n\nDevTrack sends **nothing** unless you explicitly opt in:\n\n```bash\ndevtrack telemetry status # DISABLED by default\ndevtrack telemetry on # opt in\ndevtrack telemetry off # opt back out at any time\n```\n\nIf (and only if) you opt in, the daemon sends an anonymous install/daily-active ping containing a random install UUID, a hashed hardware fingerprint, the event type (`install` / `active`), OS, arch, and version. Never code, commit text, diffs, ticket contents, or personal data.\n\nThe setting is stored locally and read directly by the daemon, so it works in every operating mode — including lightweight, with no server running.\n\n### Admin console (CS-3)\n\nA browser-based admin console built with FastAPI + HTMX. Start it with:\n\nThe admin console is server-owned. Run it from `devtrack_server/` with\n`uv run python -m backend.admin`, or set `ADMIN_EMBED=true` to mount it on the managed webhook\nserver at `/admin`. The Go client intentionally has no `admin-start` command.\n\nSign in with `ADMIN_USERNAME` / `ADMIN_PASSWORD` (set in `.env`). The dashboard shows live trigger-activity stats (triggers today, commits today, last trigger time, errors in the last 24 h) that refresh every 30 seconds via HTMX without a full page reload.\n\n**Pages and capabilities:**\n\n| Page | What you can do |\n|------|----------------|\n| **Dashboard** | Health overview, trigger throughput stats, quick links |\n| **Users** | Create/delete users, change roles (`admin` / `viewer`), disable/enable accounts, reset passwords |\n| **API Keys** | Generate and revoke per-user API keys |\n| **License** | View current license tier, seat count, and terms acceptance status |\n| **Server** | Real-time process table (CPU %, memory, health) with restart/stop/start controls |\n| **Audit Log** | Full history of all admin actions |\n\n**Single-process mode (`ADMIN_EMBED`):** By default the admin console runs as a separate process on `ADMIN_PORT` (default `8090`). Set `ADMIN_EMBED=true` to mount the admin router directly on the main webhook server at `/admin` — no extra port, no extra process:\n\n```bash\n# .env\nADMIN_EMBED=true # mount admin at /admin on the webhook server (port 8089)\n# or leave false (default) to run on a dedicated port:\nADMIN_PORT=8090\n```\n\n**Required `.env` keys for the admin console:**\n\n```bash\nADMIN_USERNAME=admin\nADMIN_PASSWORD=changeme # plain text (dev) or bcrypt hash ($2b$...)\nADMIN_SECRET_KEY= # JWT signing key — generate with: openssl rand -hex 32\nADMIN_PORT=8090 # ignored when ADMIN_EMBED=true\nADMIN_EMBED=false\n```\n\n### Runtime visibility\n\n```bash\ndevtrack status # daemon, capabilities, and managed-bootstrap progress\ndevtrack doctor # configuration and dependency diagnosis\ndevtrack doctor --repair # retry a failed managed-server bootstrap\ndevtrack tui # full-screen client dashboard\ndevtrack logs -f # follow daemon logs\n```\n\nThe Python server TUI remains available to server operators with\n`cd devtrack_server && uv run python -m backend.server_tui`; it is not a Go-client command. Its\ntrigger-throughput pane reads the Go daemon's internal stats endpoint when PostgreSQL mode is active\nand degrades to zero-valued stats when that endpoint is unavailable.\n\nThe daemon health subsystem checks these monitored services:\n\n| Check | What is verified |\n|-------|-----------------|\n| Daemon process | PID file present and process alive |\n| Python backend | `/health` HTTP endpoint reachable |\n| SQLite | Database file readable and schema valid |\n| Ollama | `/api/tags` reachable; response normalised across Ollama versions |\n| Ports | Bound ports recorded and checked across restarts |\n\nThe last-known port list is persisted so runtime diagnostics can report conflicts across restarts.\n\n---\n\n## Deployment modes\n\n| Mode | `DEVTRACK_SERVER_MODE` | How | Use case |\n|------|------------------------|-----|----------|\n| **Managed** (default) | `managed` | Daemon spawns Python automatically | Local dev — full AI features |\n| **Lightweight** | `lightweight` | Go daemon only — no Python | Git monitoring + scheduling without a Python environment |\n| **External** | `external` | Python runs on a separate server; set `DEVTRACK_SERVER_URL` | Docker / self-hosted backend |\n| **Cloud** | — | `devtrack cloud login --url URL --key KEY` | Remote managed backend |\n\n`devtrack setup` prompts for Managed or External mode on first run and writes the choice to the\ngenerated environment file. `lightweight` remains a supported manual configuration value: it maps\nto the same internal non-managed mode as `external`, so the daemon does not spawn Python. Go-native\nfeatures continue; server-backed calls use the configured (or loopback fallback) URL and degrade if\nno backend is reachable.\n\n> DevTrack runs **natively** — a Go binary plus a `uv`-managed Python server. The Go client keeps its\n> offline source of truth in local SQLite and does not connect to a database server. PostgreSQL is\n> mandatory for Python-server persistence and server-side events; MongoDB remains optional as a\n> Teams voice-learning source. Server startup validates PostgreSQL and advances the Alembic schema\n> before accepting traffic; there is no server-side SQLite fallback.\n\n### Python AI server\n\n**Managed mode** (default): `devtrack setup` configures the deterministic server location and starts\na background sparse checkout into `~/.local/share/devtrack/server/`, followed by `uv sync` and, for\nthe local Ollama provider only, a model pull when no usable generation model is already installed.\nAn opted-in cloud-key fast lane remains a fallback behind Ollama, so local inference takes over as\nsoon as the model is ready. The wizard does not wait for these steps;\n`devtrack doctor` shows durable progress and failures. No manual dependency setup is needed.\n\n**External mode** (server on a separate host): clone the repo on that host,\n`cd devtrack_server && uv sync && uv run python -m backend.webhook_server`.\nSet `DEVTRACK_SERVER_URL` on the client machine.\n\nSee [docs/INSTALLATION.md](docs/INSTALLATION.md) for the full setup walkthrough.\n\n---\n\n## Technology\n\n| Layer | Stack |\n|-------|-------|\n| Daemon / CLI | Go 1.24+, fsnotify, robfig/cron, modernc/sqlite |\n| AI backend | Python 3.12+, uv, aiohttp, LLM-first structured task parsing |\n| Local LLM | Ollama (default) · OpenAI · Anthropic · Groq · LM Studio |\n| Storage | Client SQLite (offline state), server PostgreSQL (required), ChromaDB (RAG), optional MongoDB |\n| Remote control | Go-native Telegram bot · outbound Slack webhook notifier |\n| PM integrations | Azure DevOps · GitLab · GitHub · Jira REST APIs |\n| Admin console | FastAPI + HTMX, JWT auth, bcrypt passwords, PostgreSQL-backed user/audit data |\n| Observability | runtime-narrative — structured story/stage traces on every webhook request |\n| Config discipline | All Python modules use `backend.config.get()` — no `os.getenv()` calls in business logic |\n\n---\n\n## Documentation\n\nFull user guides live on the project website: **[devtrack.cloud](https://devtrack.cloud)**.\n\nKey references in this repo:\n\n| I want to… | Go to |\n|-----------|-------|\n| Understand where the product is going | [**PRODUCT_BIBLE.md**](PRODUCT_BIBLE.md) — the source of truth |\n| Install it | [Installation](docs/INSTALLATION.md) |\n| Understand the architecture | [Architecture](docs/ARCHITECTURE.md) |\n| Maintain the Go↔Python HTTP boundary | [HTTP API contract](docs/HTTP_API.md) |\n| Review what DevTrack wants to send | [Pending-actions queue](#the-pending-actions-queue--nothing-is-sent-without-review) |\n| See the client↔server split | [Decoupling plan](docs/CLIENT_SERVER_DECOUPLING_PLAN.md) · [Capability ownership](docs/CAPABILITIES_OWNERSHIP.md) |\n| Set up the Telegram bot | [Telegram](docs/TELEGRAM_BOT.md) |\n| Set up interactively (new users) | [`devtrack setup`](#interactive-setup-wizard-devtrack-setup) |\n| Run without Python (Lightweight mode) | [Deployment modes](#deployment-modes) |\n| Deploy only the Python backend on a server | [Python AI server](#python-ai-server) |\n| Manage users, licenses, and API keys in a browser | [Admin Console](#admin-console-cs-3) |\n| Update / remove DevTrack | [`devtrack upgrade`](#self-update-devtrack-upgrade) · [`devtrack uninstall`](#uninstall-devtrack-uninstall) |\n| Understand the development-agent roles and authorization boundaries | [Agent role contract](.claude/memory/project_local_agents.md) · [archived Claude definitions](.claude/agents/_archive/) |\n| Connect Claude Code via MCP (Phase 8) | [MCP Integration](#claude-code--mcp-integration-phase-8) |\n\n---\n\n## Releasing\n\nThe canonical release pipeline is [`.github/workflows/release.yml`](.github/workflows/release.yml).\nIt runs when an authorized maintainer pushes a semantic-version tag:\n\n```bash\nGIT_NO_DEVTRACK=1 git tag -a vX.Y.Z -m \"Release vX.Y.Z\"\nGIT_NO_DEVTRACK=1 git push origin vX.Y.Z\n```\n\nGitHub Actions runs the Go tests, cross-compiles Linux amd64/arm64, macOS amd64/arm64, and Windows\namd64, validates the generated MCPB manifests, then publishes the platform binaries/tarballs and\nfive matching `.mcpb` bundles. It also publishes SHA-256 checksums, `server.json`, and the official\nMCP Registry record through GitHub OIDC. v3.1.0 is the first release produced by this complete path.\nUpdate release-facing website copy in the same release change.\n\nThe older `scripts/release.ps1` helper is retained for local maintainer workflows, but it is not the\nsource of truth for published asset names or CI behavior.\n\n---\n\n## Testing\n\n```bash\ncd devtrack_client && go test ./... # Go client suite\ncd devtrack_client && go vet ./... # lint\n\ncd devtrack_server && uv sync # uv manages the venv — never pip\ncd devtrack_server && uv run pytest backend/tests/ # Python server suite\ncd devtrack_server && uv run pytest backend/tests/ -k # filter by name\n```\n\nPython business logic must use `backend.config` typed accessors rather than adding direct environment\nreads. Missing required variables produce a `ConfigError` with the variable name rather than a\nsilent `None`.\n\n---\n\n## Privacy\n\n**The default Go + SQLite + Ollama path is local and works without internet.** Configured external\nservices receive the minimum context required for the operation you enabled.\n\n- **Cloud LLMs are optional.** OpenAI/Anthropic/Groq are used only if configured. The prompt may\n include commit messages, diff context, or work text required by the feature being invoked; do not\n enable a cloud provider if that conflicts with project policy.\n- **Nothing is posted without review.** All outbound actions are staged in the pending-actions queue until you approve them.\n- **Telemetry is opt-in** and off by default (`devtrack telemetry status`). No pings are sent unless you run `devtrack telemetry on`.\n- **Voice learning is local in managed mode by default.** Git-history seeding is local; Teams and\n external-server learning sources require explicit configuration. Learning data can be wiped with\n `devtrack learning-reset`.\n\n---\n\n## License\n\nDevTrack Community License — free for personal use and teams up to 10 users. Enterprise (11+ users) requires a paid license.\n\n```bash\ndevtrack terms # read the terms\ndevtrack terms --accept # accept non-interactively (e.g. in CI)\n```\n\nFull text: [TERMS.md](TERMS.md)\n",
"bytes": 37569,
"sha": "3c47621c695a902f791db2aa906516983a49cc498ad8482a528766342bbd809e",
"repo_slug": "sraj0501/devtrack_",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_sraj0501_devtrack_715cb907/readme"
}