{"id":50472426,"url":"https://github.com/semcod/lane","last_synced_at":"2026-06-01T11:03:34.149Z","repository":{"id":360485481,"uuid":"1250367000","full_name":"semcod/lane","owner":"semcod","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T16:45:52.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T17:08:44.141Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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-05-26T16:45:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/lane","commit_stats":null,"previous_names":["semcod/lane"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/lane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Flane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Flane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Flane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Flane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/lane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Flane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33771630,"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-01T02:00:06.963Z","response_time":115,"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":[],"created_at":"2026-06-01T11:03:34.043Z","updated_at":"2026-06-01T11:03:34.138Z","avatar_url":"https://github.com/semcod.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lane\n\n\n## AI Cost Tracking\n\n![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.20-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)\n![AI Cost](https://img.shields.io/badge/AI%20Cost-$1.38-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-8.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)\n\n- 🤖 **LLM usage:** $1.3762 (23 commits)\n- 👤 **Human dev:** ~$828 (8.3h @ $100/h, 30min dedup)\n\nGenerated on 2026-05-31 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)\n\n---\n\n`lane` 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## 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** — `lane plan`, `lane auto`, `lane metrics`, `lane print-context`, `lane print-prompt`, `lane validate`, `lane 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 .\nlane print-prompt .\n```\n\nTo generate a real plan, set `OPENROUTER_API_KEY` or `OPENAI_API_KEY` and run:\n\n```bash\nlane plan . --extra-context \"What should we build next for this repository?\"\n```\n\nOutput as JSON:\n\n```bash\nlane plan . --json\n```\n\nInspect captured project and git context without calling the LLM:\n\n```bash\nlane print-context .\n```\n\nValidate a saved plan file:\n\n```bash\nlane validate plan.json\n```\n\nAnalyze code metrics and coupling:\n\n```bash\nlane metrics .\n```\n\n## CLI Reference\n\n### `lane plan`\nGenerate a 10-task engineering plan for a repository.\n\n**Usage:**\n```bash\nlane 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### `lane print-context`\nPrint the assembled project and git context without calling the LLM.\n\n**Usage:**\n```bash\nlane 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### `lane print-prompt`\nPrint the full prompt that would be sent to the LLM.\n\n**Usage:**\n```bash\nlane 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### `lane validate`\nValidate a saved JSON plan file against the TaskPlan schema.\n\n**Usage:**\n```bash\nlane validate PLAN_FILE\n```\n\n### `lane 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\nlane 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\nlane auto\n\n# With extra context\nlane auto . -e \"Focus on security improvements\"\n\n# Dry run to preview\nlane auto --dry-run\n```\n\n**Equivalent to:**\n```bash\nlane tickets . --koru-aware --sync-planfile\n```\n\n### `lane metrics`\nDisplay comprehensive code metrics for the project including cyclomatic complexity, change coupling, bug hotspots, and bus factor analysis.\n\n**Usage:**\n```bash\nlane 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\nlane metrics .\n\n# Show top 5 with higher coupling threshold\nlane metrics . --top 5 --min-coupling 0.5\n```\n\n### `lane 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\nlane 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\nlane tickets .\n\n# Sync to TODO.md\nlane tickets . --sync-todo\n\n# Export to planfile YAML\nlane tickets . --export-yaml --output strategy.yaml\n\n# Koru-aware planning (generates tasks referencing koru operations)\nlane 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\"\nlane plan /path/to/project --extra-context \"Focus on improving test coverage\"\n```\n\n### Use a custom model\n```bash\nlane plan . --model \"openrouter/anthropic/claude-3.5-sonnet\"\n```\n\n### Inspect what data is sent to the LLM\n```bash\nlane print-prompt . --extra-context \"Review security issues\"\n```\n\n### Generate a plan and save as JSON\n```bash\nlane plan . --json \u003e plan.json\nlane validate plan.json\n```\n\n### Analyze a project with limited git history\n```bash\nlane 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\nlane auto\n\n# With custom focus\nlane auto . -e \"Refactor authentication system\"\n```\n\n### Code metrics analysis\n\n```bash\n# Full metrics report\nlane metrics .\n\n# High coupling files\nlane metrics . --top 10 --min-coupling 0.6\n```\n\n### Koru-aware planning\n\n```bash\nlane tickets . --koru-aware --sync-planfile\n```\n\n## Architecture\n\n### Modules\n\n- **lane.project_analyzer** — Project analysis (manifests, structure, stack)\n- **lane.git_reader** — Git history analysis\n- **lane.metrics** — Code metrics (complexity, coupling, hotspots)\n- **lane.koru_context** — Koru framework integration\n- **lane.planner** — Orchestrates analysis → LLM → TaskPlan\n- **lane.providers** — Pluggable LLM backends\n- **lane.ticket_generator** — Planfile integration\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** `lane auto` command — one-command workflow (analyze + generate + sync)\n- **Added** `lane metrics` command (complexity, coupling, hotspots, bus factor)\n- **Added** `--koru-aware` flag for koru-integrated planning\n- **Added** `lane.metrics` module\n- **Added** `lane.koru_context` module\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%2Flane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Flane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Flane/lists"}