{"id":30862319,"url":"https://github.com/glottologist/towl","last_synced_at":"2026-04-01T19:39:05.780Z","repository":{"id":308691643,"uuid":"1033698240","full_name":"glottologist/towl","owner":"glottologist","description":"Cargo plugin for tracking TODO comments and linking them to Github issues","archived":false,"fork":false,"pushed_at":"2026-03-31T14:59:46.000Z","size":5895,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T16:38:42.991Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://glottologist.github.io/towl/","language":"Rust","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/glottologist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-08-07T08:01:26.000Z","updated_at":"2026-03-31T14:59:51.000Z","dependencies_parsed_at":"2025-08-07T11:12:20.187Z","dependency_job_id":"b42a834b-39c6-46ce-a0fd-f1a073e0711d","html_url":"https://github.com/glottologist/towl","commit_stats":null,"previous_names":["glottologist/towl"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/glottologist/towl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glottologist%2Ftowl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glottologist%2Ftowl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glottologist%2Ftowl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glottologist%2Ftowl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glottologist","download_url":"https://codeload.github.com/glottologist/towl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glottologist%2Ftowl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2025-09-07T17:14:24.645Z","updated_at":"2026-04-01T19:39:05.771Z","avatar_url":"https://github.com/glottologist.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# towl 🦉\n\n![TODOOwl](./docs/media/towl_trans_small.png)\n\nA fast command-line tool that scans your codebase for TODO comments, lets you browse them in an interactive TUI, and optionally creates GitHub issues from them.\n\n## Features\n\n- **AI Validation**: Use `--ai` to validate TODOs with an LLM (Claude API, OpenAI API, or local CLI agents like Claude Code and Codex) -- filters stale TODOs and enriches GitHub issues\n- **Interactive TUI**: Browse, filter, sort, and peek at TODOs in a full-screen terminal interface\n- **GitHub Integration**: Create GitHub issues from selected TODOs and replace comments with issue links\n- **Smart Detection**: Finds TODO, FIXME, HACK, NOTE, and BUG comments\n- **Multiple Output Formats**: JSON, CSV, Markdown, TOML, terminal table (non-interactive mode)\n- **Filtering \u0026 Sorting**: Filter by TODO type, sort by file, line, type, or priority\n- **Fast**: Async I/O, concurrent file scanning, compiled regex patterns\n- **Configurable**: Customise file extensions, patterns, and exclusions via `.towl.toml` (override with `--config` or `TOWL_CONFIG` env var)\n- **Context-Aware**: Shows surrounding code lines and enclosing function names\n\n## Installation\n\n```bash\ncargo install towl\n```\n\n## Quick Start\n\n```bash\n# Scan current directory (opens interactive TUI)\ntowl scan\n\n# Scan in non-interactive mode (CI/scripting)\ntowl scan -N\n\n# Output to JSON file\ntowl scan -N -f json -o todos.json\n\n# Filter by type\ntowl scan -N -t todo\n\n# Create GitHub issues from TODOs\ntowl scan -N -g\n\n# Preview GitHub issues without creating them\ntowl scan -N -g -n\n\n# AI-validate TODOs (filters out stale ones)\ntowl scan -N --ai\n\n# AI + GitHub: create issues for valid TODOs only\ntowl scan -N --ai -g\n\n# Use a config file from a custom path\ntowl scan -c .config/.towl.toml\n\n# Initialise config\ntowl init\n\n# Show current config\ntowl config\n\n# Show config from a custom path\ntowl config -c .config/.towl.toml\n```\n\n## Usage\n\n```bash\ntowl scan [OPTIONS] [PATH]\n\nOptions:\n  -c, --config \u003cPATH\u003e       Path to a .towl.toml configuration file\n  -N, --non-interactive     Disable interactive TUI mode (for CI/scripting)\n  -f, --format \u003cFORMAT\u003e     Output format (non-interactive only) [default: terminal]\n                            [possible values: table, json, csv, toml, markdown, terminal]\n  -o, --output \u003cOUTPUT\u003e     Output file path (required for json, csv, toml, markdown)\n  -t, --todo-type \u003cTYPE\u003e    Filter by TODO type\n                            [possible values: todo, fixme, hack, note, bug]\n  -v, --verbose             Enable verbose output\n  -g, --github              Create GitHub issues for found TODOs\n  -n, --dry-run             Preview GitHub issues without creating them\n      --ai                  Analyse TODOs with AI to validate relevance\n\ntowl init [OPTIONS]\n\nOptions:\n  -p, --path \u003cPATH\u003e         Config file path [default: .towl.toml]\n  -F, --force               Overwrite existing config file\n\ntowl config [OPTIONS]       Show current configuration\n\nOptions:\n  -c, --config \u003cPATH\u003e       Path to a .towl.toml configuration file\n```\n\n## Interactive TUI\n\nBy default, `towl scan` opens an interactive terminal interface:\n\n| Key | Action |\n|-----|--------|\n| `j` / `Down` | Move cursor down |\n| `k` / `Up` | Move cursor up |\n| `Space` | Toggle selection |\n| `a` | Select all visible |\n| `n` | Deselect all |\n| `f` | Cycle type filter |\n| `s` | Cycle sort field (file, line, type, priority) |\n| `r` | Reverse sort order |\n| `p` | Peek at source code around the TODO |\n| `d` | Delete selected invalid TODOs (with `--ai`) |\n| `Enter` | Confirm selection and create GitHub issues |\n| `q` / `Esc` | Quit |\n\nUse `--non-interactive` / `-N` to bypass the TUI for CI pipelines and scripting.\n\n## Configuration\n\nCreate a `.towl.toml` file in your project root (or run `towl init`). To load from a different path, use `--config` / `-c` or set `TOWL_CONFIG`:\n\n```toml\n[parsing]\nfile_extensions = [\"rs\", \"toml\", \"json\", \"yaml\", \"yml\", \"sh\", \"bash\"]\nexclude_patterns = [\"target/*\", \".git/*\"]\ninclude_context_lines = 10\n\n[llm]\nprovider = \"claude\"           # \"claude\", \"openai\", \"claude-code\", or \"codex\"\nmodel = \"claude-opus-4-6\"\n```\n\nGitHub owner and repo are always auto-detected from `git remote get-url origin` at runtime. Set secrets via environment variables (never stored in the config file):\n\n| Variable | Description |\n|----------|-------------|\n| `TOWL_CONFIG` | Path to a `.towl.toml` file (overridden by `--config`) |\n| `TOWL_GITHUB_TOKEN` | GitHub personal access token |\n| `TOWL_LLM_API_KEY` | LLM API key (Claude or OpenAI) |\n\nSee the [configuration guide](https://glottologist.github.io/towl/getting-started/configuration.html) for all options.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglottologist%2Ftowl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglottologist%2Ftowl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglottologist%2Ftowl/lists"}