{
  "markdown": "# DevTime\n\n**DevTime verifies what your repository can actually prove.**\n\nA file named `stripe/webhook.ts` looks like proof that a repo handles Stripe\nwebhooks. It might be a handler that only returns 404. DevTime checks statements\nabout a repository against its implementation, tests, configuration, and recorded\ndecisions, then reports what is supported, what is contradicted, what is missing,\nand what went stale.\n\n> No cloud. No telemetry. No code execution. No AI required.\n\n![DevTime verify demo - a claim goes from SUPPORTED to CONTRADICTED to STALE](assets/devtime-verify-demo.svg)\n\nPrefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans\na repo locally, explains concepts from evidence, surfaces uncertainty, catches a\nrisky diff, and shows how a corroborated decision improves understanding.\n\n---\n\n## Try DevTime in 60 seconds\n\n```bash\npipx install devtime-ei\ndtc demo init\ncd devtime-demo-saas\ndtc init\ndtc scan\ndtc verify\n```\n\nOn the demo repo that ends with signature verification SUPPORTED, JWT\nauthentication SUPPORTED, and `2 of 3 routes have a referencing test`. Point it at\nyour own repository and the answers change:\n\n```bash\ncd your-repo\ndtc init && dtc scan && dtc verify\n```\n\nThe PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the\nCLI command remains `dtc`. `dtc demo init` copies a small static example repo into\n`./devtime-demo-saas` so you can try DevTime without cloning this repository.\n\n### From source\n\n```bash\ngit clone https://github.com/Shakargy/devtime.git\ncd devtime\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\ncd examples/demo-saas\ndtc init\ndtc scan\ndtc concepts\ndtc explain \"Billing Webhooks\"\n```\n\nOn Windows PowerShell:\n\n```powershell\ngit clone https://github.com/Shakargy/devtime.git\ncd devtime\npython -m venv .venv\n.venv\\Scripts\\Activate.ps1\npip install -e \".[dev]\"\ncd examples/demo-saas\ndtc init\ndtc scan\ndtc concepts\ndtc explain \"Billing Webhooks\"\n```\n\nYou should see Billing Webhooks explained from evidence, including supported claims,\nfile references, uncertainty, Understanding Score, and Understanding Debt.\n\nTo test risk review, make a local change first, then run:\n\n```bash\ndtc risk --diff\n```\n\nA full, copy-pasteable walkthrough (including the risk-diff and corroborated-decision\nsteps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.\n\n## Verify claims (experimental)\n\nA claim is a statement about the repository. Verification answers it with a\nstatus and receipts, never with confidence the evidence cannot back.\n\n```text\nStatus: CONTRADICTED\n\nContradictions:\n  - The billing webhook endpoint cannot verify signatures\n    because it is a disabled stub.\n      claimed:  pages/api/stripe/webhook.ts is named and routed\n                as a billing webhook endpoint.\n      observed: The handler's only behavior is a 404/501 response.\n```\n\n- **SUPPORTED** - required behavior evidence exists in the current scan\n- **WEAK** - the surface exists, but the proving evidence is missing\n- **CONTRADICTED** - credible evidence conflicts with the claim, both sides shown\n- **UNKNOWN** - the surface exists but coverage cannot responsibly decide\n- **NOT_APPLICABLE** - the repository has no surface this claim is about\n\nFour built-in claims ship: route test coverage, admin authorization, billing\nwebhook signatures, and JWT authentication. `dtc verify` leads with what it can\nactually verify in your repository, and when nothing applies it says what would\nmake a claim verifiable instead of dead-ending.\n\nTruth and freshness are separate: when a file behind a verified claim changes,\nthe claim goes STALE and names the file. `dtc risk --diff` reports which verified\nclaims a diff destabilizes.\n\nSee **[VERIFICATION.md](VERIFICATION.md)** for the full model and its limits.\n\n## Why this exists\n\nGit records what changed, but it does not preserve the reasoning behind those\nchanges. When you return to a repository - or review one you did not write - you often\nhave to reconstruct why a behavior exists, what evidence supports it, and what is\nstill uncertain.\n\nDevTime builds evidence-backed repository memory: a local layer that helps a\ncodebase explain itself from code, tests, configs, routes, and recorded decisions.\nIt shows what the repository can support with evidence - and, just as importantly,\nwhat it cannot support yet.\n\n## Who it is for\n\nDevTime is for people who need to understand a repository from evidence rather than\nmemory.\n\nIt is especially useful if you:\n\n- are onboarding to an unfamiliar codebase and need to understand how a feature is implemented;\n- are reviewing a pull request and want to see what evidence supports a behavior;\n- are returning to a project after weeks or months and cannot remember why something exists;\n- maintain a long-lived project where design decisions are easily lost;\n- want repository understanding to be backed by code and recorded decisions instead of generated summaries.\n\nQuestions DevTime helps answer include:\n\n- Can this repository actually prove the thing its file names imply?\n- Where is authentication actually implemented?\n- What files prove that Billing Webhooks exist?\n- What is still uncertain?\n- Did this diff touch a risky concept?\n- Is there a decision explaining this behavior?\n\n## What DevTime does\n\n- Verifies claims about a repository and reports status, evidence, and both sides\n  of any contradiction.\n- Tracks freshness, so a verified claim goes stale when the evidence behind it changes.\n- Detects concepts from routes, tests, configs, dependencies, and docs.\n- Explains from evidence by linking claims to files and signals.\n- Surfaces uncertainty when evidence is missing or weak.\n- Scores understanding with an Understanding Score and Understanding Debt label.\n- Reviews narrow risky diffs with advisory findings, including which verified\n  claims a diff destabilizes.\n- Records decisions locally so rationale can reduce uncertainty when corroborated by code.\n\n## Supported concepts\n\nUnderneath verification is a scanner that builds local, evidence-backed memory:\n\n![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)\n\nDevTime detects six supported concept families. It does not discover arbitrary\ndomain concepts yet:\n\n- Authentication\n- Billing Webhooks\n- Background Jobs\n- Data Export\n- Admin Permissions\n- File Uploads\n\nAnything outside these six is out of scope for now. See [LIMITATIONS.md](LIMITATIONS.md).\n\n## What DevTime does not do\n\n- It does not execute your code.\n- It does not send code or data over the network.\n- It does not require or call an AI model.\n- It does not guarantee correctness or safe changes.\n- It does not replace code review or architecture decisions.\n- It is **not** a documentation generator, a static analyzer, an observability tool,\n  a productivity tracker, or an AI coding agent.\n\n## Trust model\n\n- DevTime stores local repository memory in `.devtime/` (a local SQLite database).\n- **No network access** during a scan.\n- **No code execution** during a scan.\n- Ignored directories are pruned *before* scanning; ignored files and secrets must\n  never become evidence or claims.\n- Every claim must link to evidence - *no claim without evidence*.\n- Weak evidence produces **uncertainty**, not confidence.\n- *Usage is not decision*: that a dependency is used does not mean someone decided why.\n- Risk review is **advisory** by default - it does not block PRs.\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `dtc init` | Create local `.devtime` memory. |\n| `dtc scan` | Scan the current repository and extract evidence-backed signals. |\n| `dtc concepts` | List detected concepts with confidence and Understanding Debt. |\n| `dtc explain <concept>` | Explain a concept: claims, evidence, confidence, uncertainty, Understanding Debt. |\n| `dtc context <concept>` | Create a governed Context Pack for agents or humans. |\n| `dtc risk --diff` | Review a git diff for risky changes using local evidence (advisory). |\n| `dtc decision add` | Add a local decision record that can reduce uncertainty. |\n| `dtc verify [claim]` | Verify repository claims against evidence: status, contradictions, freshness (experimental). |\n\n(Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,\n`dtc export`, `dtc reset`, `dtc mcp start`.)\n\nRequires **Python >= 3.11** and git. See **[QUICKSTART.md](QUICKSTART.md)** for a\nstep-by-step first run and troubleshooting.\n\n## Use with coding agents (MCP)\n\nYour coding agent starts every session amnesiac about your repository and then\nguesses, confidently. DevTime gives it memory it can trust: a local, read-only MCP\nserver that answers only with claims the repository can prove, plus explicit\nuncertainty for what it cannot.\n\nInstall with MCP support and scan your repo:\n\n```bash\npipx install \"devtime-ei[mcp]\"\ncd your-repo\ndtc init\ndtc scan\n```\n\nAdd DevTime to Claude Code:\n\n```bash\nclaude mcp add devtime -- dtc mcp start\n```\n\nOr in any MCP client that reads `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"devtime\": {\n      \"command\": \"dtc\",\n      \"args\": [\"mcp\", \"start\"]\n    }\n  }\n}\n```\n\nThe agent gets four read-only tools: `list_concepts`, `explain_concept`,\n`get_context_pack` (governed context with do-not-change-without-review paths, tests\nto run, and agent guidance), and `verify_claim` (claim status, contradictions, and\nmissing evidence, computed fresh and never persisted). Local stdio only - no network listener, no write tools,\nno source code returned, only evidence file paths.\n\nDevTime is listed in the official MCP Registry as `io.github.Shakargy/devtime`.\n\n<!-- mcp-name: io.github.Shakargy/devtime -->\n\n## Installation\n\nRecommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`\ncommand is available on your PATH in an isolated environment:\n\n```bash\npipx install devtime-ei\n```\n\nOr with pip:\n\n```bash\npip install devtime-ei\n```\n\nThe PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the\nCLI command remains `dtc`. After installing, run `dtc demo init` to create a local\nexample repo to try it on.\n\n### From source\n\n```bash\ngit clone https://github.com/Shakargy/devtime.git\ncd devtime\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https://github.com/Shakargy/devtime.git\ncd devtime\npython -m venv .venv\n.venv\\Scripts\\Activate.ps1\npip install -e \".[dev]\"\n```\n\n## Example output\n\n```\n$ dtc explain \"Billing Webhooks\"\nConcept: Billing Webhooks\n\nSupported claims:\n  - Billing Webhooks is present and supported by behavior evidence.\n    type: concept  confidence: 0.86  evidence: src/billing/stripe-webhook.ts, tests/stripe-signature.test.ts\n  - Billing Webhooks has active route handling.\n    type: behavior  confidence: 0.82  evidence: src/billing/stripe-webhook.ts\n  - Billing Webhooks verifies webhook signatures.\n    type: behavior  confidence: 0.85  evidence: src/billing/stripe-webhook.ts\n\nUncertainty:\n  - No decision was found explaining key choices for Billing Webhooks.\n\nUnderstanding Score: 58 / 100\nUnderstanding Debt: medium\ncauses:\n  - missing or uncorroborated decision evidence\n  - no confirmed owner\n```\n\n> Understanding Score is higher = better understanding; Understanding Debt is a\n> label (low/medium/high), not the same number.\n\n## Proof\n\nDevTime runs on `examples/demo-saas` and on real repositories. During Reality\nValidation it detected - and then learned from - real failures (Next.js App Router\nblindness, a false Billing Webhooks detection on a generic webhook system, a DB\nmigration mis-counted as Background Jobs evidence, and more). Each failure became a\nfixture so it cannot silently regress.\n\n- Tests grew from 13 to 88 as real failures became fixtures.\n- Scan time on a 355-file real repo dropped from ~27.3s to ~0.48s after ignored-\n  directory pruning.\n\nFull evidence, before/after examples, and the validation reports are in\n**[PROOF.md](PROOF.md)** and `reports/reality-validation/`.\n\n## Privacy and safety\n\n- Runs entirely locally; nothing leaves your machine during a scan.\n- No code execution and no network calls during scanning.\n- Secrets and ignored files are excluded from evidence by design (`dtc doctor\n  --privacy` reports the boundaries).\n- `dtc reset` deletes local memory; your source code is never modified.\n\n## Known limitations\n\nDevTime is a **heuristic scanner**, not a full compiler or semantic analyzer. It is\ncurrently strongest on TypeScript / Next.js / Express / FastAPI-style repositories\nthat resemble its fixtures. False positives and false negatives are possible.\nUnderstanding Debt is a product signal, not an objective universal truth.\n\nRead the full list - including framework coverage, risk-review scope, and what is\nintentionally not built yet - in **[LIMITATIONS.md](LIMITATIONS.md)**.\n\n## Roadmap\n\nThis is an early, local-first V0 focused on being trustworthy before being large.\nNot yet built (intentionally): git-history signals, write-enabled MCP tools, an AI\nprovider, a UI, and any cloud/team/enterprise features. See **[ROADMAP.md](ROADMAP.md)**.\n\n## Contributing\n\nThe most valuable contribution is a **fixture**: a small repository pattern plus the\nexpected concepts, allowed claims, forbidden claims, and required uncertainty. If\nDevTime gets something wrong on your code, that wrong output can become a fixture so\nit never regresses. See **[CONTRIBUTING.md](CONTRIBUTING.md)**.\n\n## License\n\nLicensed under the **Apache License 2.0**. See [LICENSE](LICENSE).\n",
  "bytes": 13521,
  "sha": "c4888c0135b409d38ba23a7610fe094cd87130e6772f8e927ebaa4765d817ed4",
  "repo_slug": "shakargy/devtime",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shakargy_devtime_ad1506c7/readme"
}