- π€ LLM usage: $10.9961 (74 commits)
- π€ Human dev: ~$2040 (20.4h @ $100/h, 30min dedup)
Generated on 2026-07-06 using openrouter/deep/deep-v4-pro
Progressive algorithmization toolchain β from LLM to deterministic code, from proxy to tickets.
The only framework that automates the path from "LLM handles everything" to "most traffic runs deterministically, LLM only for edge cases."
pip install algitex
algitex init ./my-app
algitex go
The name reflects the core cycle: analyze β plan β execute β validate β repeat. Each iteration makes your codebase healthier and your LLM usage cheaper. The progressive algorithmization loop gradually replaces LLM calls with deterministic rules.
Algitex = Algorithmic + Intelligence + Execution + Engine
Semantically:
- Alg- β algorithms, logic, determinism
- -i- β intelligence layer
- -tex β texture / system / framework / execution layer
Algitex is the intelligence compilation engine that transforms LLM-driven behavior into deterministic, cost-efficient algorithmic systems. It enables progressive algorithmization from probabilistic AI reasoning to structured, deterministic logic.
The 5-stage transition from LLM to deterministic:
Stage 1: Discovery β LLM performs tasks, collect traces
Stage 2: Extraction β Identify recurring patterns
Stage 3: Rules β Generate deterministic replacements
Stage 4: Hybrid β Route by confidence: rules vs LLM
Stage 5: Optimization β Minimize LLM dependency, reduce costs
Result: Systems that start with LLM flexibility but evolve into efficient, deterministic enginesβmaintaining AI reasoning benefits with traditional software performance.
| Name | Why it works | Why we picked algitex |
|---|---|---|
| algitex | Core concept: the continuous improvement loop | Clear, memorable, tech-neutral |
| prollama | "progressive" + llama vibes | Ties too much to one model family |
| codefact | Code + factory/fact | Sounds like a trivia app |
| algopact | Algorithm + Propact | Hard to pronounce |
| loopcode | Loop + code | Reverse reads awkward |
| prodev | Progressive + dev | Too generic, SEO nightmare |
from algitex import Project p = Project("./my-app") p.analyze() # code2llm + vallm + redup β health report p.plan() # auto-generate tickets from analysis p.execute() # LLM handles tasks via proxym p.status() # health + tickets + budget + cost ledger
from algitex import Loop loop = Loop("./my-app") loop.discover() # Stage 1: collect all LLM traces loop.extract() # Stage 2: find repeating patterns loop.generate_rules() # Stage 3: AI writes its own replacement loop.route() # Stage 4: rules vs LLM by confidence loop.optimize() # Stage 5: monitor, minimize LLM usage print(loop.report()) # "42% deterministic, $12.50 saved"
from algitex import Workflow wf = Workflow("./refactor-v1.md") wf.execute() # runs propact:shell, propact:rest, propact:llm blocks
algitex init ./my-app # initialize project algitex analyze # health check algitex plan --sprints 3 # generate sprint strategy + tickets algitex go # full pipeline algitex status # dashboard
algitex algo discover # start trace collection algitex algo extract # find patterns in traces algitex algo rules # generate deterministic replacements algitex algo report # show % deterministic vs LLM
algitex workflow run fix.md # execute Markdown workflow algitex workflow validate f.md
algitex ticket add "Fix auth" --priority high algitex ticket list algitex ticket board algitex sync # push to GitHub/Jira
algitex ask "Explain this race condition" --tier premium algitex tools # show installed tools
## Parallel TODO Task Processing
Execute TODO tasks from prefact analysis in parallel with automatic categorization and fix strategies:
```bash
# Verify which TODO tasks are still valid vs already fixed
algitex todo verify-prefact
# Remove outdated tasks from TODO.md
algitex todo verify-prefact --prune
# BatchFix: grupowanie i optymalizacja podobnych zadaΕ
algitex todo batch --dry-run # Symulacja
algitex todo batch --execute # Wykonaj fixy
algitex todo batch --limit 10 --parallel 2 # Limit i rΓ³wnolegΕoΕΔ
algitex todo batch --execute --prune # Wykonaj + wyczyΕΔ nieaktualne
algitex todo batch --execute --no-log # WyΕΔ
cz logowanie markdown
algitex todo batch --model qwen2.5-coder:7b # WybΓ³r modelu Ollama
# Auto-fix mechanical issues in parallel (dry-run)
algitex todo fix-auto --workers 8
# Actually apply fixes
algitex todo fix-auto --execute
Pipeline for breaking down and executing atomic micro-tasks optimized for small LLMs:
# Classify tasks by complexity algitex microtask classify # Generate execution plan algitex microtask plan # Execute micro-tasks algitex microtask run --workers 4
Deterministic NLP-based refactoring without LLM calls:
# Fix docstrings algitex nlp docstrings --dry-run algitex nlp docstrings --execute # Optimize imports algitex nlp imports --execute # Remove dead code algitex nlp dead-code --execute # Find and refactor duplicates algitex nlp duplicates --execute
Measure and compare performance across cache, tiers, and memory usage:
# Quick benchmark (30 seconds) algitex benchmark quick # Test cache performance algitex benchmark cache --entries 100 --lookups 500 # Compare tier throughput algitex benchmark tiers # Memory profiling for large files algitex benchmark memory --lines 1000 # Full benchmark suite with export algitex benchmark full --export results.json
Live TUI dashboard for monitoring algitex operations:
# Live dashboard with auto-refresh algitex dashboard live # Dashboard for 60 seconds algitex dashboard live --duration 60 # Monitor existing cache/metrics algitex dashboard monitor --cache .algitex/cache --metrics .algitex/metrics.json # Export metrics to JSON algitex dashboard export --format json --output metrics.json --duration 60 # Export to Prometheus format algitex dashboard export --format prometheus --output metrics.prom
algitex todo fix --all --dashboard
algitex todo hybrid --execute --dashboard
algitex todo batch --execute --dashboard
### Python API
```python
from algitex.todo import verify_todos, fix_todos, benchmark_fix, compare_modes
# Verify task validity
result = verify_todos("TODO.md")
print(f"Still open: {result.still_open}, Fixed: {result.already_fixed}")
# Parallel auto-fix (mechanical tasks only)
stats = fix_todos("TODO.md", workers=8, dry_run=False)
print(f"Fixed: {stats['fixed']}, Skipped: {stats['skipped']}")
# Benchmark performance
result = benchmark_fix("TODO.md", limit=100, workers=8, mode="parallel")
result.print_report()
# Compare modes
comparison = compare_modes("TODO.md", limit=50, workers=8)
### Auto-fix Categories
| Category | Auto-fixable | Description |
|----------|--------------|-------------|
| `unused_import` | β
Yes | Remove unused imports (import X, from Y import X) |
| `return_type` | β
Yes | Add missing return type annotations |
| `fstring` | β οΈ Partial | Convert concatenations to f-strings |
| `magic` | β
Yes | Suggest names for magic numbers |
| `docstring` | β
Yes | Rewrite verbose docstrings |
| `rename` | β
Yes | Improve variable names |
| `split_function` | β
Yes | Extract methods from large functions |
| `dependency_cycle` | β
Yes | Break import cycles |
| `architecture` | β
Yes | Reorganize module structure |
| `other` | β οΈ Varies | Complex issues requiring reasoning |
### How Parallel Processing Works
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β Parallel TODO Processing β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ β β β 1. Parse TODO.md β filter worktree duplicates β β 2. Categorize tasks (unused_import, return_type...) β β 3. Group by file (1 worker per file, zero conflicts) β β 4. Sort tasks bottom-up (line DESC) β preserve numbers β β 5. Execute in ThreadPoolExecutor (8 workers default) β β 6. Collect results: fixed, skipped, errors β β β β Safety: Each worker touches different file. β β Within file: bottom-up prevents line number shifts. β β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
### Three Execution Paths
| Path | LLM? | Parallel? | Throughput | Use Case |
|------|------|-----------|------------|----------|
| `todo fix-auto` | β No | β
Yes (8 workers) | ~1500 tickets/sec | Mechanical fixes: unused imports, return types |
| `todo run --tool ollama-mcp` | β
Yes | β Sequential (queue) | ~1-10 tickets/sec | Complex fixes requiring reasoning |
| `autofix via proxy` | β
Yes | β οΈ Batch | ~5-50 tickets/sec | Intelligent fixes via litellm-proxy |
**When to use which:**
**Path 1: Mechanical Fixes (`todo fix-auto`)**
- No LLM calls β pure regex/text manipulation
- 8 parallel workers, thread-safe per-file isolation
- Handles: `unused_import`, `return_type`, `fstring` (via flynt)
- Best for: bulk cleanup of 100+ simple issues
```python
from algitex.todo import fix_todos
stats = fix_todos("TODO.md", workers=8, dry_run=False)
# 2679 tasks β ~1.8 seconds total
Path 2: LLM-based Fixes (todo run)
- Uses Ollama/aider via Docker MCP
- Sequential execution (respects LLM rate limits)
- Handles: complex refactoring, architectural changes
- Best for: issues requiring code understanding
algitex todo run --tool ollama-mcp --limit 10
Path 3: Hybrid via Proxy (autofix)
- Routes through litellm-proxy with cost tracking
- Batch processing with retry logic
- Handles: smart fixes with context awareness
- Best for: production workflows with budget constraints
from algitex.tools.autofix import AutoFix autofix = AutoFix(backend="litellm-proxy", proxy_url="http://localhost:4000") autofix.fix_all(limit=5) # $0.12 per batch avg
Path 4: Hybrid CLI (todo hybrid) β Fast + Parallel + LLM
- Phase 1: Parallel mechanical fixes (no LLM)
- Phase 2: Rate-limited parallel LLM fixes
- Handles: complete TODO workflow in one command
# Dry run (preview) algitex todo hybrid --workers 4 --rate-limit 10 # Execute with rate limiting algitex todo hybrid --execute --backend litellm-proxy --workers 4 --rate-limit 10 # Local Ollama (100% offline) algitex todo hybrid --execute --backend ollama --workers 2 --rate-limit 5
To achieve szybkie + rΓ³wnolegΕe + LLM, you need to combine ThreadPoolExecutor with ProxyBackend:
from algitex.todo import HybridAutofix # Combines parallel task distribution with LLM backend fixer = HybridAutofix( backend="litellm-proxy", workers=4, # Parallel workers rate_limit=10, # Requests per second retry_attempts=3, timeout=30 ) # Mechanical fixes: parallel, no LLM fixer.fix_mechanical("TODO.md") # 1000+ tickets/sec # Complex fixes: parallel LLM with rate limiting fixer.fix_complex("TODO.md") # 10-50 tickets/sec, cost-tracked
Requirements for parallel LLM:
- Rate limiting (prevent 429 errors)
- Retry logic with exponential backoff
- Cost tracking per batch
- Circuit breaker for failed requests
Stage 1: Discovery β LLM handles 100%, collect traces
Stage 2: Extraction β identify hot paths + repeating patterns
Stage 3: Rules β AI generates deterministic replacements
Stage 4: Hybrid β confidence-based: known patterns β rules, unknown β LLM
Stage 5: Optimization β most traffic deterministic, LLM for edge cases only
No existing framework automates this path. DSPy goes LLMβsmaller LLM. algitex goes LLMβalgorithm.
Analyze current state:
code2llm ./src/auth -f toon --json
Ask LLM for a fix plan:
POST http://localhost:4000/v1/chat/completions
{"model": "balanced", "messages": [{"role": "user", "content": "Fix auth"}]}
Validate the result:
vallm batch ./src/auth --recursive
## Planfile-Aware Proxy Headers
Every LLM request through algitex carries context:
X-Planfile-Ref: my-project/current/DLP-0042 X-Workflow-Ref: refactor-v1.md X-Task-Tier: complex X-Inject-Context: true
Proxym logs cost/model/latency **per ticket**. The cost ledger shows exactly what each task costs.
## Installation
```bash
pip install algitex # core
pip install algitex[all] # + all tools
pip install algitex[proxy] # + proxym
pip install algitex[analysis] # + code2llm, vallm, redup
pip install algitex[tickets] # + planfile
pip install algitex[routing] # + llx
cd examples/01-quickstart make run
cd examples/02-algo-loop make run
cd examples/03-pipeline make run
cd examples/04-ide-integration make setup && make run
cd examples/05-cost-tracking make run
cd examples/18-ollama-local make setup && make run
cd examples/19-local-mcp-tools make up && make run
cd examples/20-self-hosted-pipeline make build && make up && make run
cd examples/21-aider-cli-ollama make setup && make run
cd examples/22-claude-code-ollama make setup && make run
cd examples/23-continue-dev-ollama make setup
cd examples/24-ollama-batch python batch_analyze.py --dir ./src
cd examples/25-local-model-comparison make benchmark
cd examples/26-litellm-proxy-ollama make setup && make proxy # Terminal 1 make fix # Terminal 2
cd examples/33-hybrid-autofix make dry-run # Preview make hybrid # Execute with LiteLLM proxy make ollama # Execute with Ollama (100% offline)
cd examples/34-batch-fix algitex todo batch --dry-run # Symulacja algitex todo batch --execute # Wykonaj fixy
Each example has:
- [01-quickstart/README.md](examples/01-quickstart/README.md) β Project, Loop, Workflow basics
- [02-algo-loop/README.md](examples/02-algo-loop/README.md) β Progressive algorithmization
- [03-pipeline/README.md](examples/03-pipeline/README.md) β Composable fluent API
- [04-ide-integration/README.md](examples/04-ide-integration/README.md) β IDE configs
- [05-cost-tracking/README.md](examples/05-cost-tracking/README.md) β Cost tracking
- [06-telemetry/README.md](examples/06-telemetry/README.md) β Telemetry & observability
- [07-context/README.md](examples/07-context/README.md) β Context building
- [08-feedback/README.md](examples/08-feedback/README.md) β Feedback loops
- [09-workspace/README.md](examples/09-workspace/README.md) β Workspace management
- [10-cicd/README.md](examples/10-cicd/README.md) β CI/CD pipelines
- [11-aider-mcp/README.md](examples/11-aider-mcp/README.md) β Aider MCP code refactoring
- [12-filesystem-mcp/README.md](examples/12-filesystem-mcp/README.md) β Filesystem operations
- [13-vallm/README.md](examples/13-vallm/README.md) β Vallm validation
- [14-docker-mcp/README.md](examples/14-docker-mcp/README.md) β Docker container management
- [15-github-mcp/README.md](examples/15-github-mcp/README.md) β GitHub repository operations
- [16-test-workflow/README.md](examples/16-test-workflow/README.md) β Comprehensive test pipeline
- [17-docker-workflow/README.md](examples/17-docker-workflow/README.md) β Refactoring workflow
- [18-ollama-local/README.md](examples/18-ollama-local/README.md) β Local LLM with Ollama (100% offline)
- [19-local-mcp-tools/README.md](examples/19-local-mcp-tools/README.md) β Self-hosted MCP tools (Docker)
- [20-self-hosted-pipeline/README.md](examples/20-self-hosted-pipeline/README.md) β Complete local CI/CD pipeline
- [21-aider-cli-ollama/README.md](examples/21-aider-cli-ollama/README.md) β Aider CLI + Ollama local refactoring
- [22-claude-code-ollama/README.md](examples/22-claude-code-ollama/README.md) β Claude Code + Ollama AI assistant
- [23-continue-dev-ollama/README.md](examples/23-continue-dev-ollama/README.md) β Continue.dev VS Code extension + Ollama
- [24-ollama-batch/README.md](examples/24-ollama-batch/README.md) β Parallel batch processing with Ollama
- [25-local-model-comparison/README.md](examples/25-local-model-comparison/README.md) β Benchmark Ollama models
- [26-litellm-proxy-ollama/README.md](examples/26-litellm-proxy-ollama/README.md) β LiteLLM Proxy + Ollama (native algitex)
- [28-mcp-orchestration/README.md](examples/28-mcp-orchestration/README.md) β MCP Service Orchestration
- [30-parallel-execution/README.md](examples/30-parallel-execution/README.md) β Parallel Execution with Region-Based Coordination
- [31-abpr-workflow/README.md](examples/31-abpr-workflow/README.md) β ABPR Workflow
- [32-workspace-coordination/README.md](examples/32-workspace-coordination/README.md) β Multi-Repo Workspace Coordination
- [33-hybrid-autofix/README.md](examples/33-hybrid-autofix/README.md) β Fast parallel + LLM with rate limiting
- [34-batch-fix/README.md](examples/34-batch-fix/README.md) β BatchFix: grupowanie i optymalizacja fixΓ³w
- [35-sprint3-patterns/README.md](examples/35-sprint3-patterns/README.md) β Sprint 3 CC Reduction Patterns
- [36-dashboard/README.md](examples/36-dashboard/README.md) β Live Dashboard TUI
- [37-benchmarks/README.md](examples/37-benchmarks/README.md) β Performance Benchmarks
- [38-new-modules/README.md](examples/38-new-modules/README.md) β New Module Usage
- [39-microtask-pipeline/README.md](examples/39-microtask-pipeline/README.md) β MicroTask Pipeline
- [40-three-tier-autofix/README.md](examples/40-three-tier-autofix/README.md) β Three-Tier AutoFix
- [41-god-module-splitting/README.md](examples/41-god-module-splitting/README.md) β God Module Splitting
- [42-duplicate-removal/README.md](examples/42-duplicate-removal/README.md) β Duplicate Code Removal
- [43-code-health/README.md](examples/43-code-health/README.md) β Code Health Monitoring
- [44-plugin-system/README.md](examples/44-plugin-system/README.md) β Plugin System Architecture
- `run.sh` β executable script
- `Makefile` β `make run`, `make setup`, `make clean`
- `.env.example` β configuration template (where applicable)
> β
**44 examples available** (2026-04-25). Examples 01-34 tested and verified working.
## Additional Documentation
- [README2.md](./README2.md) β Detailed conceptual overview of Algitex as intelligence compilation engine
- [docs/todo.md](./docs/todo.md) β TODO task processing and BatchFix
- [docs/BATCHFIX.md](./docs/BATCHFIX.md) β BatchFix: grupowanie i optymalizacja fixΓ³w
- [docs/MICROTASK.md](./docs/MICROTASK.md) β Atomic micro-tasks for small LLMs
- [docs/NLP.md](./docs/NLP.md) β Deterministic NLP refactor helpers
- [docs/NEW_FEATURES.md](./docs/NEW_FEATURES.md) β Overview of new modules and features
- [docs/autofix.md](./docs/autofix.md) β AutoFix module documentation
- [docs/REFACTORING_SUMMARY.md](./docs/REFACTORING_SUMMARY.md) β Codebase refactoring summary
## Architecture
src/algitex/ βββ init.py # Project, Loop, Workflow, Config, Pipeline βββ config.py # Unified config (env + YAML) βββ project.py # Main Project class (expanded) βββ cli.py # Typer CLI backward compatibility shim βββ cli/ # Modular CLI commands β βββ init.py # Main app with all subcommands β βββ core.py # init, analyze, plan, go, status β βββ ticket.py # Ticket management β βββ algo.py # Progressive algorithmization β βββ workflow.py # Propact workflows β βββ docker.py # Docker MCP tools β βββ todo.py # TODO processing β βββ microtask.py # Atomic micro-task pipeline β βββ nlp.py # Deterministic NLP helpers β βββ metrics.py # Metrics and observability β βββ benchmark.py # Performance benchmarks β βββ dashboard.py # Real-time monitoring βββ algo/ # Progressive algorithmization β βββ init.py # Loop, TraceEntry, Pattern, Rule, LoopState β βββ loop.py # Re-export βββ propact/ # Markdown workflow engine β βββ init.py # Workflow, WorkflowStep, WorkflowResult β βββ workflow.py # Re-export βββ todo/ # TODO fixing system (Sprint 3: CC reduced) β βββ init.py # Public API exports β βββ fixer.py # Orchestrator (was 724L, now ~450L) β βββ classify.py # Task classification (CC: 50β4) β βββ repair.py # Repair strategies (CC: 30β6) β βββ verify.py # Verification pipeline (CC: 29β5) β βββ micro.py # Small LLM fixes β βββ hybrid.py # Big LLM fixes β βββ tiering.py # Task classification helpers β βββ benchmark.py # Performance benchmarking βββ microtask/ # Atomic tasks for small LLMs β βββ init.py # MicroTask, TaskType, MicroTaskBatch β βββ classifier.py # Task classification β βββ executor.py # Three-phase execution β βββ slicer.py # Context extraction βββ nlp/ # Deterministic NLP refactors β βββ init.py # DocstringShortener, DeadCodeDetector, etc. βββ tools/ β βββ init.py # Tool discovery β βββ proxy.py # proxym wrapper + planfile headers β βββ analysis.py # code2llm + vallm + redup β βββ tickets.py # planfile wrapper + cost ledger βββ workflows/ βββ init.py # Pipeline (composable steps) βββ pipeline.py # Re-export
## How it connects to the ecosystem
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β algitex β β (orchestration layer) β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ β β β analyze() plan() execute() algo.discover() β β β β β β β β code2llm planfile proxym trace β β β vallm tickets llx patterns β β β redup strategy models rules β β β hybrid routing β β β β MicroTask Pipeline: β β microtask classify β atomic task decomposition β β microtask plan β execution strategy β β microtask run β three-phase execution β β β β NLP Helpers (deterministic): β β nlp docstrings β shorten verbose docs β β nlp imports β sort and organize β β nlp dead-code β detect unused functions β β nlp duplicates β find repeated blocks β β β β run_workflow("fix.md") β β β β β propact:shell β subprocess β β propact:rest β httpx β β propact:llm β proxym β β propact:mcp β MCP tool call β β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
## Tool Roles
| Tool | What | Install |
|------|------|---------|
| **proxym** | LLM gateway, 10 providers, routing, budget | `pip install proxym` |
| **planfile** | Sprint planning, tickets, GitHub/Jira sync | `pip install planfile` |
| **llx** | Metric-driven model selection, MCP server | `pip install llx` |
| **code2llm** | Static analysis β .toon diagnostics | `pip install code2llm` |
| **vallm** | 4-tier code validation | `pip install vallm` |
| **redup** | Duplication detection | `pip install redup` |
## License
Licensed under Apache-2.0.
## Status
_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 09:28 UTC_
| Metric | Value |
|---|---|
| HEAD | `6e56e90` |
| Coverage | β |
| Failing tests | β |
| Commits in last cycle | 50 |
> The project focused on extensive refactoring of documentation and examples, along with fixes and features enhancing the CLI interface and deep code analysis engine.
<!-- taskill:status:end -->
<!-- taskill:status:start -->
## Status
_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 18:20 UTC_
| Metric | Value |
|---|---|
| HEAD | `41621f3` |
| Coverage | β |
| Failing tests | β |
| Commits in last cycle | 0 |
> No changes since the last taskill run: there are no new commits and no modified files, so no code or TODO state has been updated.
<!-- taskill:status:end -->