{"id":51339619,"url":"https://github.com/semcod/nxdo","last_synced_at":"2026-07-02T06:04:37.003Z","repository":{"id":360485481,"uuid":"1250367000","full_name":"semcod/nxdo","owner":"semcod","description":"Generate the next 10 project tasks from project state, git history and an LLM prompt.","archived":false,"fork":false,"pushed_at":"2026-06-18T11:25:14.000Z","size":1398,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T12:28:20.129Z","etag":null,"topics":["git","llm","planning","project-management","python","roadmap","semcod","tasks"],"latest_commit_sha":null,"homepage":"https://semcod.github.io/nxdo/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semcod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-05-26T15:01:26.000Z","updated_at":"2026-06-18T12:00:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/nxdo","commit_stats":null,"previous_names":["semcod/lane","semcod/nxdo"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/nxdo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnxdo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnxdo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnxdo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnxdo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/nxdo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnxdo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35035001,"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-07-02T02:00:06.368Z","response_time":173,"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":["git","llm","planning","project-management","python","roadmap","semcod","tasks"],"created_at":"2026-07-02T06:04:36.260Z","updated_at":"2026-07-02T06:04:36.987Z","avatar_url":"https://github.com/semcod.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nxdo\n\n\n## AI Cost Tracking\n\n![AI Cost](https://img.shields.io/badge/AI%20Cost-$4.50-green) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fqwen%2Fqwen3-coder-next-lightgrey)\n\nThis project uses AI-generated code. Total cost: **$4.5000** with **30** AI commits.\n\nGenerated on 2026-06-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/models/openrouter/qwen/qwen3-coder-next)\n\n---\n\n`nxdo` is a Python package that inspects the current project state, reads recent git history, adds a user question for an LLM, and returns a concrete plan for the next 10 engineering tasks.\n\n**Documentation:** [docs/](docs/) · **Examples:** [examples/](examples/) · **Step-by-step guide:** [docs/how-it-works.md](docs/how-it-works.md)\n\n## How it works (step by step)\n\n1. **Analyze the repo** — README, manifests, tree, stack (`project_analyzer`)\n2. **Read git context** — commits, changed files, TODO/FIXME markers (`git_reader`)\n3. **Optional metrics** — complexity, coupling, hotspots (`metrics`)\n4. **Build prompt** — snapshot + git + your `--extra-context` (`llm_client`)\n5. **Call LLM** — OpenAI-compatible API, default OpenRouter (`providers`)\n6. **Validate plan** — 10 tasks as Pydantic `TaskPlan` (`models`)\n7. **Output** — terminal, JSON, TODO.md, or `.planfile/` (`tickets`, `auto`)\n\n```bash\npip install nxdo\nexport OPENROUTER_API_KEY=\"your-key\"\n\n# 1–2: inspect context (no API cost)\nnxdo print-context .\n\n# 3: metrics only (no API cost)\nnxdo metrics .\n\n# 4–6: generate plan\nnxdo plan . -e \"What should we build next?\"\n\n# 7: export or sync tickets\nnxdo plan . --json \u003e plan.json\nnxdo tickets . --sync-planfile\n```\n\nReal outputs from running nxdo **on this repo**: [examples/nxdo-self-plan.json](examples/nxdo-self-plan.json) · [examples/nxdo-self-plan.txt](examples/nxdo-self-plan.txt) · [examples/nxdo-self-context.txt](examples/nxdo-self-context.txt) · [examples/nxdo-self-prompt.txt](examples/nxdo-self-prompt.txt) · [examples/nxdo-self-metrics.txt](examples/nxdo-self-metrics.txt)\n\nVerify: `./examples/check-examples.sh`\n\nSee the full walkthrough in [docs/how-it-works.md](docs/how-it-works.md).\n\n## What is included\n\n- **Project snapshot analysis** — README, manifests (pyproject.toml, package.json, Cargo.toml, …), directory tree, stack detection\n- **Git context** — recent commits, most-changed files, TODO/FIXME markers\n- **Advanced code metrics** — cyclomatic complexity, coupling analysis, bug hotspots, bus factor detection\n- **Koru-aware planning** — Deep integration with koru framework for intelligent task generation\n- **Pydantic models** — validated data models for tasks and plans (`Task`, `TaskPlan`)\n- **Provider abstraction** — pluggable LLM backends; ships with an OpenAI-compatible provider (works with OpenRouter and any OpenAI-style API)\n- **Planner orchestrator** — `generate_next_tasks()` composes analysis + prompt + LLM call into a validated TaskPlan\n- **Rich CLI** — `nxdo plan`, `nxdo auto`, `nxdo metrics`, `nxdo print-context`, `nxdo print-prompt`, `nxdo validate`, `nxdo tickets`\n- **Reliability** — `httpx` for HTTP, `tenacity` for automatic retry/backoff, `pydantic-settings` for environment config\n\n## Quick start\n\n```bash\npython -m venv .venv\n. .venv/bin/activate\npip install -e .\nnxdo print-prompt .\n```\n\nTo generate a real plan, set `OPENROUTER_API_KEY` or `OPENAI_API_KEY` and run:\n\n```bash\nnxdo plan . --extra-context \"What should we build next for this repository?\"\n```\n\nOutput as JSON:\n\n```bash\nnxdo plan . --json\n```\n\nInspect captured project and git context without calling the LLM:\n\n```bash\nnxdo print-context .\n```\n\nValidate a saved plan file:\n\n```bash\nnxdo validate plan.json\n```\n\nAnalyze code metrics and coupling:\n\n```bash\nnxdo metrics .\n```\n\n## CLI Reference\n\n### `nxdo plan`\nGenerate a 10-task engineering plan for a repository.\n\n**Usage:**\n```bash\nnxdo plan [REPO_PATH] [OPTIONS]\n```\n\n**Options:**\n- `--extra-context, -e TEXT`: Additional prompt context for the LLM\n- `--model, -m TEXT`: Override the LLM model name\n- `--base-url TEXT`: Override the API base URL\n- `--json`: Output plan as JSON instead of formatted text\n- `--max-commits INTEGER`: How many recent commits to inspect (default: 30)\n\n### `nxdo print-context`\nPrint the assembled project and git context without calling the LLM.\n\n**Usage:**\n```bash\nnxdo print-context [REPO_PATH] [OPTIONS]\n```\n\n**Options:**\n- `--max-commits INTEGER`: How many recent commits to inspect (default: 30)\n- `--raw`: Print raw text instead of Rich panels\n\n### `nxdo print-prompt`\nPrint the full prompt that would be sent to the LLM.\n\n**Usage:**\n```bash\nnxdo print-prompt [REPO_PATH] [OPTIONS]\n```\n\n**Options:**\n- `--extra-context, -e TEXT`: Additional prompt context for the LLM\n- `--max-commits INTEGER`: How many recent commits to inspect (default: 30)\n\n### `nxdo validate`\nValidate a saved JSON plan file against the TaskPlan schema.\n\n**Usage:**\n```bash\nnxdo validate PLAN_FILE\n```\n\n### `nxdo auto`\nAuto-generate and sync tickets for the most important work. This is the quickest way to get actionable tickets into your planfile.\n\n**Usage:**\n```bash\nnxdo auto [REPO_PATH] [OPTIONS]\n```\n\n**What it does:**\n1. Analyzes project for high-priority issues (hotspots, complexity, coupling)\n2. Generates tickets using koru-aware planning\n3. Auto-syncs to `.planfile/` for execution via koru queue\n\n**Options:**\n- `--extra-context, -e TEXT`: Additional prompt context for the LLM\n- `--dry-run`: Show what would be done without executing\n\n**Example:**\n```bash\n# Quick auto mode - analyze, generate, sync\nnxdo auto\n\n# With extra context\nnxdo auto . -e \"Focus on security improvements\"\n\n# Dry run to preview\nnxdo auto --dry-run\n```\n\n**Equivalent to:**\n```bash\nnxdo tickets . --koru-aware --sync-planfile\n```\n\n### `nxdo metrics`\nDisplay comprehensive code metrics for the project including cyclomatic complexity, change coupling, bug hotspots, and bus factor analysis.\n\n**Usage:**\n```bash\nnxdo metrics [REPO_PATH] [OPTIONS]\n```\n\n**Options:**\n- `--top, -n INTEGER`: Show top N items per category (default: 10)\n- `--min-coupling FLOAT`: Minimum coupling score to display (default: 0.3)\n\n**Metrics displayed:**\n- **Cyclomatic Complexity** per file (identify complex functions to refactor)\n- **Coupling Analysis** — which files change together frequently (plan refactors together)\n- **Coupling Clusters** — groups of tightly coupled files (sprint planning)\n- **Bug Hotspots** — files with high bug fix rate and code churn\n- **Bus Factor** — files with few authors (knowledge silos)\n\n**Example:**\n```bash\n# Show metrics for current project\nnxdo metrics .\n\n# Show top 5 with higher coupling threshold\nnxdo metrics . --top 5 --min-coupling 0.5\n```\n\n### `nxdo tickets`\nGenerate tickets from a plan using planfile integration.\n\nThis command generates tickets from a TaskPlan and optionally syncs them to TODO.md, .planfile/, or exports to planfile YAML format.\n\n**Usage:**\n```bash\nnxdo tickets [REPO_PATH] [OPTIONS]\n```\n\n**Options:**\n- `--extra-context, -e TEXT`: Additional prompt context for the LLM\n- `--model, -m TEXT`: Override the LLM model name\n- `--base-url TEXT`: Override the API base URL\n- `--max-commits INTEGER`: How many recent commits to inspect (default: 30)\n- `--sync-todo`: Sync tasks to TODO.md checkboxes using planfile\n- `--sync-planfile`: Store tickets in .planfile/ and sync with markdown\n- `--export-yaml`: Export to planfile YAML format\n- `--output, -o PATH`: Output file for YAML export\n- `--koru-aware`: Enable koru integration schema for smart task planning\n\n**Examples:**\n```bash\n# Generate and display tickets\nnxdo tickets .\n\n# Sync to TODO.md\nnxdo tickets . --sync-todo\n\n# Export to planfile YAML\nnxdo tickets . --export-yaml --output strategy.yaml\n\n# Koru-aware planning (generates tasks referencing koru operations)\nnxdo tickets . --koru-aware --sync-planfile\n```\n\n**Note:** This feature requires the planfile package. It will be auto-installed if missing.\n\n## Configuration\n\nAll settings are read from environment variables:\n\n| Variable | Default | Description |\n|---|---|---|\n| `OPENROUTER_API_KEY` | — | API key for OpenRouter (preferred) |\n| `OPENAI_API_KEY` | — | API key for OpenAI-compatible endpoint |\n| `LLM_MODEL` | `openrouter/qwen/qwen3-coder-next` | Model name |\n| `LLM_BASE_URL` | `https://openrouter.ai/api/v1` | API base URL |\n| `LLM_TIMEOUT` | `60` | HTTP timeout in seconds |\n| `LLM_MAX_RETRIES` | `3` | Number of retry attempts on network error |\n| `MAX_COMMITS` | `30` | How many recent commits to read |\n\n## Runtime dependencies\n\n- `pydantic\u003e=2`\n- `pydantic-settings\u003e=2`\n- `typer\u003e=0.12`\n- `rich\u003e=13`\n- `httpx\u003e=0.27`\n- `tenacity\u003e=8`\n\n## Examples\n\n### Generate a plan for a Python project\n```bash\nexport OPENROUTER_API_KEY=\"your-api-key\"\nnxdo plan /path/to/project --extra-context \"Focus on improving test coverage\"\n```\n\n### Use a custom model\n```bash\nnxdo plan . --model \"openrouter/anthropic/claude-3.5-sonnet\"\n```\n\n### Inspect what data is sent to the LLM\n```bash\nnxdo print-prompt . --extra-context \"Review security issues\"\n```\n\n### Generate a plan and save as JSON\n```bash\nnxdo plan . --json \u003e plan.json\nnxdo validate plan.json\n```\n\n### Analyze a project with limited git history\n```bash\nnxdo plan . --max-commits 10\n```\n\n### Quick auto mode (analyze + generate + sync)\n\n```bash\n# One command to analyze project and create tickets in planfile\nnxdo auto\n\n# With custom focus\nnxdo auto . -e \"Refactor authentication system\"\n```\n\n### Code metrics analysis\n\n```bash\n# Full metrics report\nnxdo metrics .\n\n# High coupling files\nnxdo metrics . --top 10 --min-coupling 0.6\n```\n\n### Koru-aware planning\n\n```bash\nnxdo tickets . --koru-aware --sync-planfile\n```\n\n## Architecture\n\n### Modules\n\n- **nxdo.project_analyzer** — Project analysis (manifests, structure, stack)\n- **nxdo.git_reader** — Git history analysis\n- **nxdo.metrics** — Code metrics (complexity, coupling, hotspots)\n- **nxdo.koru_context** — Koru framework integration\n- **nxdo.planner** — Orchestrates analysis → LLM → TaskPlan\n- **nxdo.providers** — Pluggable LLM backends\n- **nxdo.ticket_generator** — Planfile integration\n\n### Docs and examples\n\n- [docs/README.md](docs/README.md) — documentation index\n- [docs/how-it-works.md](docs/how-it-works.md) — pipeline and step-by-step tutorial\n- [examples/](examples/) — sample outputs from self-analysis\n\n## Development\n\n```bash\npip install -e \".[dev]\"\nPYTHONPATH=src python -m unittest discover -s tests -v\n```\n\n\n## Changelog\n\n### 0.2.x\n- **Added** `nxdo auto` command — one-command workflow (analyze + generate + sync)\n- **Added** `nxdo metrics` command (complexity, coupling, hotspots, bus factor)\n- **Added** `--koru-aware` flag for koru-integrated planning\n- **Added** `nxdo.metrics` module\n- **Added** `nxdo.koru_context` module\n- **Renamed** package from `lane` to `nxdo` on PyPI and GitHub\n- **Improved** Test coverage to 97%\n- **Improved** Refactored CC hotspots\n\n## License\n\nLicensed under Apache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fnxdo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Fnxdo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fnxdo/lists"}