| title | Command Pulse | ||||
|---|---|---|---|---|---|
| description | A backend-first deterministic WEGO military command simulation focused on FOB-level leadership in an Afghanistan-style counterinsurgency environment. | ||||
| author | CommandPulse Team | ||||
| ms.date | 2026-02-21 | ||||
| ms.topic | overview | ||||
| keywords |
|
A backend-first WEGO military command simulation focused on FOB-level leadership in an Afghanistan-style counterinsurgency environment.
Completed Core Phases: Phase 0–4 ✅
Current Phase: Phase 6 / 6.5 – CLI Playable Prototype + LLM C2 🚧 In Progress
Deferred: Phase 4.1, 4.2, 5 (post-CLI playtesting)
Core simulation systems (WEGO engine, logistics, combat/morale, insurgent AI) are complete and covered by tests. Current development focuses on CLI playability and natural-language command & control integration.
See ROADMAP.md for full development plan.
See docs/phase4_completion.md for insurgent-system completion.
See docs/phase6.5_llm_c2_system.md and docs/ROADMAP_PHASE_6.5.0_NEXT_STEPS.md for active work.
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Setup project
make setup
source .venv/bin/activate
# Run tests
uv run pytest tests/ -v
# Run Phase 1 demo (20 pulses)
uv run python run_20_pulses.py
# Run Phase 2 demo (convoy mission with 6 pulses)
uv run python run_phase2_demo.py
# Run Phase 3 demo (15-pulse combat patrol)
uv run python run_phase3_demo.pyPhase 3 Complete: Full combat system with CombatResolver, morale/fatigue, order compliance, and patrol suppression mechanics.
See docs/phase0_architecture.md for technical architecture.
See UV Quick Reference for UV commands.
You are the commander of a Forward Operating Base.
You do not control soldiers directly. You issue intent every 10 in-game minutes. The simulation resolves consequences simultaneously.
This is a game about:
- Logistics pressure
- Miscommunication
- Ambush risk
- Morale degradation
- Delayed consequences
- Imperfect intelligence
Inspired by U.S. FOB layouts in Afghanistan:
- Walled perimeter
- Entry control points
- Guard towers
- TOC (Tactical Operations Center)
- Motor pool
- Ammunition and fuel storage
- Barracks and aid station
- Supply yards
- Convoy routes through hostile terrain
The FOB is a functional system node. It consumes and distributes supply.
10-minute command cycles.
- Convoy scheduling
- Route interdiction
- Supply attrition
- Fuel and ammunition tracking
- FOB supply management
- Resupply operations (see design_fob_resupply.md for Phase 3/5+ design)
- Affects combat effectiveness
- Affects order compliance
- Influences reaction time
- Order clarity degrades
- Units interpret intent
- Chain-of-command friction
- Asymmetric tactics
- IEDs
- Ambushes
- Resource-driven operations
Emergency pulses triggered by:
- Ambushes
- FOB perimeter breach
- Intelligence breakthrough
- Catastrophic supply failure
Backend-first. Simulation-first. Deterministic core.
LLMs assist strategy and reporting, never core mechanics.
The CLI natural-language system supports both local Ollama and OpenRouter.
Default behavior uses Ollama:
export COMMANDPULSE_LLM_PROVIDER=ollama
export OLLAMA_MODEL=llama3To switch to OpenRouter free models:
export COMMANDPULSE_LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your_api_key_here
export OPENROUTER_MODEL=meta-llama/llama-3.3-8b-instruct:freeOptional shared tuning knobs:
export COMMANDPULSE_LLM_TEMPERATURE=0.5
export COMMANDPULSE_LLM_MAX_TOKENS=70
export COMMANDPULSE_LLM_TIMEOUT=60- Language: Python 3.10+
- Package Manager: UV (fast, deterministic)
- Testing: pytest
- Type Checking: mypy
- Formatting: Black
- Linting: pylint
See copilot-instructions.md for full development guidelines.
- 1 FOB
- 2 Friendly squads
- 1 Supply route
- 1 Insurgent cell
- Pulse engine
- Combat resolution
- Morale & fatigue
- Interrupts
No graphics. CLI-based prototype.
- Multiple FOB network
- Persistent campaign
- Sector control map
- Political pressure layer
- Civilian population modeling
- Multiplayer WEGO