███████╗ ██████╗ ██╗ ██╗███████╗ ██████╗ ██████╗ ██████╗ ███████╗
██╔════╝██╔═══██╗╚██╗██╔╝██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
█████╗ ██║ ██║ ╚███╔╝ █████╗ ██║ ██║██████╔╝██║ ███╗█████╗
🭏 🭏 ██╔══╝ ██║ ██║ ██╔██╗ ██╔══╝ ██║ ██║██╔══██╗██║ ██║██╔══╝
▄██▄▄██ ██║ ╚██████╔╝██╔╝ ██╗██║ ╚██████╔╝██║ ██║╚██████╔╝███████╗
▄███████▄ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝
███▀ ▀███
███ ███ ██████╗ ██████╗ ██████╗ ███████╗
██████████ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
████████████\ ██║ ██║ ██║██║ ██║█████╗
████████████ ███ ██║ ██║ ██║██║ ██║██╔══╝
███ ███ ██ █████ ╚██████╗╚██████╔╝██████╔╝███████╗
███ ███ ███ ████ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
A local-only terminal coding assistant. No API keys. No cloud. No subscriptions.
Foxforge-code is a TUI-first fork of Foxforge stripped down to coding workflows. It drops the web GUI and the general-purpose conversation layer, and replaces them with a direct coding assistant (Fox), a grounded web research pipeline (DeepFox), and a project workspace that tracks everything locally.
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp config.ini.example config.ini
./start_foxforge_code.sh --check
python3 -m SourceCode.tui.appSee INSTALL_GUIDE.md for Ollama setup and optional bot integrations.
/msg routes to Fox: a direct, no-personality coding assistant. Fox answers questions about the active project, suggests architecture, reviews code, and helps debug. It knows the project name, description, stack, and workspace path from the project record.
Fox does not search the web. If it doesn't have enough to answer, it says so and suggests /forage <query>.
/forage, /forage --domain, and /forage --intent <name> run the full research pipeline under the hood. DeepFox is the orchestration layer — no personality, no editorializing, no injecting its own ideas into summaries. It reports what the evidence shows, flags gaps, and stops.
Both modes share the same pipeline skeleton. What differs is the lens at each stage.
Use this when you want to understand how to build something: architectural tradeoffs, implementation patterns, libraries, risk, ecosystem maturity.
- Persona-driven discovery — 4 roles (Product Manager, Market Analyst, Project Manager, Tech Lead) each generate one search query based on the project context and research question. 4 parallel web crawls × 20 results each = 80 candidate sources.
- Diversity filtering — each persona bucket is ranked by source tier × topical relevance × intra-bucket diversity. Top 8 per persona = 32 curated sources fed to the research pool.
- Research pool — role-routed agents work the sources via topic policy + intent policy:
- Router inputs:
topic_type,research_intent, query, project context, workspace knowledge - Role classes:
primary,advisory,adjudicator - Gating: legal and quantitative roles are trigger-based, not unconditional
- Animal-care routing is split from medical to avoid human-clinical drift
- Router inputs:
- Synthesis → Skeptic pass → Gap-fill (if confidence is low)
Use this when you want to understand a subject area itself: what experts actually know, what users actually experience, and what authoritative resources define the field. This is the right mode for product research, content strategy, learning path design, or any question about a domain rather than an implementation.
The logic behind the split: technical sources (Stack Overflow, GitHub, engineering blogs) are noise for domain questions, and domain sources (practitioner communities, certification bodies, user forums) are noise for implementation questions. Sending the wrong agents at the wrong sources produces confident-sounding synthesis with the wrong signal.
- Persona-driven discovery — 3 domain-specific roles generate queries oriented toward expert knowledge, user experience, and authoritative references rather than implementation.
- Diversity filtering — same ranking as technical mode, but source tier calibration favors domain authorities over technical publishers.
- Research pool — domain-intent roles prioritize:
domain_practitioner_researcherend_user_researcherresource_scout(advisory, claims filtered from evidence aggregation)- plus trigger-gated roles when relevant (safety, standards/certification, legal, quantitative)
- Synthesis → Skeptic pass → Gap-fill (if confidence is low)
research_intent is now first-class and threads through the stack:
general_researchdomain_foragingproduct_researchtechnical_planningimplementation_supportmarket_researchstandards_researchrisk_researchfinal_synthesis
/forage --domain maps to domain_foraging by default. /forage --intent <name> lets you set intent explicitly.
In project-bound forage:
- Always translate findings to project context.
- Only translate into stack-specific implementation actions when intent is
technical_planningorimplementation_support. - Otherwise technical notes are framed under Possible Technical Implications instead of direct Tech Lead actions.
The synthesizer produces a unified narrative — not a per-agent summary. Key findings are tagged:
[baseline]— well-known consensus; compressed to one sentence[insight]— non-obvious, differentiating finding; given full treatment[risk]— specific failure mode or when-it-breaks scenario; given full treatment[gap]— no primary evidence found; stated explicitly
Required sections: Executive Summary, Key Findings, Insights & Design Implications (≥2 non-obvious items), Failure Modes & Risks (≥2 specific scenarios), Differentiation Opportunity, Next Steps.
Evidence labels: [E] (evidence — cite a source URL), [I] (inference), [S] (speculation). Convergence is reported as "N of M agents supported X" — when all agents cite the same source type, that's flagged as an echo, not independent validation.
- Tier 1 — official docs, language references, package registries, standards bodies, security advisories, technical specifications
- Tier 2 — maintained repos, Stack Overflow, engineering blogs, established technical publishers, reputable practitioner communities
- Tier 3 — community forums, tutorial sites, dev blogs, Medium posts, Reddit threads
- Tier 4 — cross-domain analogy sources; cannot support evidence claims
If most sources are tier 3/4, synthesis confidence is capped and a Source Quality Warning is added.
Research output is written to Projects/<slug>/research_summaries/ and Projects/<slug>/research_raw/.
Additional artifacts now include:
<summary>.primitives.jsonfor domain primitives (milestones,success_criteria,failure_modes,measurement_dimensions)domain_summary(domain forage runs)project_summaryandimplementation_brief(technical planning runs)
- Skeptic sidecar: adversarial critique/revise pass after synthesis.
- Genericity/usefulness gate: scores artifacts and triggers at most one rewrite when outputs are too generic.
- Recommendation-strength labels on actions:
implement_now,prototype,design_option,future_experiment,weak_do_not_prioritize,reject. - Public-content guardrail: unsafe/public-content requests are filtered before synthesis output is finalized.
- Scaffold/documentation system references include Canon v1 and optional runtime smoke validation paths.
The interface is built with Textual. Key features:
- Animated fox in the banner — breathing color, occasional tail wag, hop, and turn. Phrases and intervals are configurable in
SourceCode/tui/indicator_phrases.py. - Thinking indicator — shows current pipeline stage and elapsed time. Label cycles through task-specific phrases (chat / forage / plan / build) every 5–7 seconds. During
/forage, each research stage (agent running, web crawl, skeptic review, etc.) updates the label live. - Project footer — shows
Name [slug]at the bottom center, always visible. - Autocomplete —
↑/↓cycles through matching commands./opentab-completes your project slugs from the live database. - File path highlighting — any existing file path in the reasoning stream is highlighted amber+underline. VS Code's terminal link provider makes them Ctrl+Clickable.
| Command | What it does |
|---|---|
/new greenfield <name> <description> |
Scaffold a new project. Stack is auto-detected from the description. |
/new import <git-url|path> [--copy] [--name <name>] |
Import an existing codebase. |
/projects |
List all projects. |
/open <slug|id> |
Switch active project. |
| Command | What it does |
|---|---|
/msg <text> |
Chat with Fox about the active project. No web access. |
/forage <query> |
Run the full research pipeline — technical mode. Targets implementation, architecture, and ecosystem questions. |
/forage --domain <query> |
Run the full research pipeline — domain mode. Targets expert knowledge, user experience, and authoritative resources rather than implementation. |
/forage --intent <name> <query> |
Run forage with explicit intent routing (for example technical_planning, implementation_support, domain_foraging). |
/plan [prompt] |
Generate a markdown plan for the project. |
/execute --plan <id|latest> |
Run a plan. |
/build [prompt] |
Plan + execute in one shot. |
| Command | What it does |
|---|---|
/view |
Render the most recent research summary in the TUI. |
/view --summary |
Most recent research summary (timestamp-prefixed files only). |
/view --raw |
Most recent raw research notes. |
/view --fancy |
Open the file via grip in the browser for rendered markdown. |
/view --summary --fancy |
Summary in browser. |
/view --raw --fancy |
Raw notes in browser. |
| Command | What it does |
|---|---|
/stack show |
Show the active project's current stack. |
/stack change <backend> <frontend> <db> <lang> |
Override the stack. |
/stack save <name> |
Save as a reusable custom stack. |
/git init|status|commit|push |
Project-scoped git operations. |
/models |
List configured model roles. |
/models set <role> <model> |
Reassign a model role. |
/system |
Show repo root, paths, and runtime info. |
/help |
List all commands. |
/quit |
Exit. |
/new greenfield detects the stack from your description:
| Description signals | Detected stack |
|---|---|
vue, react, svelte, htmx, angular |
Frontend set accordingly |
node, typescript, javascript, hono, next |
Hono + Svelte + SQLite |
django |
Django + htmx + Postgres |
flask |
Flask + htmx + SQLite |
desktop, .net, dotnet, avalonia |
Avalonia + none + none |
cli, terminal, tool, script, bot, daemon, simple |
No frontend |
| Default (web app) | FastAPI + htmx + SQLite |
Override anytime with /stack change <backend> <frontend> <db> <lang>.
If a request is treated as a system-level stack decision, re-evaluate from a Technical topic before re-running research.
Current scaffolding includes system-fixed tracks for Flask 3.x + Vue 3.5 and .NET 8 + Avalonia alongside other templates. These are referred to as system-fixed stacks in internal docs and tests.
Available stack components:
- Backends:
fastapiflaskdjangoexpresshononextjs-apiavalonia - Frontends:
nonehtmxreactvuesvelteangular - Databases:
sqlitepostgresmongodbjson-file - Languages:
pythonnodedotnetgorust
All model roles are set in config.ini under [models]. Changes take effect on the next command — no restart needed.
Key roles:
| Role key | Default | Used for |
|---|---|---|
reynard_layer |
qwen3:8b |
Fox chat responses (/msg) |
intent_confirmer |
gemma3:4b |
Intent verification gate (skip list covers most commands) |
research_market_analyst |
qwen3:8b |
Research pool baseline lane config |
research_technical |
deepseek-r1:8b |
Legacy technical-role compatibility |
research_critical_analyst |
deepseek-r1:8b |
Adjudicator role (in-pool) |
research_critical_analyst_premium |
hengwen/DeepSeek-R1-Distill-Qwen-14B:q4_k_m |
Premium escalation for critical analyst |
research_contrarian_red_team_premium |
hengwen/DeepSeek-R1-Distill-Qwen-14B:q4_k_m |
Premium escalation for contrarian/red-team |
synthesis_default |
qwen3:8b |
Research synthesis |
synthesis_premium |
hengwen/DeepSeek-R1-Distill-Qwen-14B:q4_k_m |
Escalated synthesis (skeptic-triggered) |
research_genericity_gate |
qwen3:8b |
Genericity/usefulness scoring and rewrite gating |
plan_deep |
qwen3:14b |
Deep plan generation |
plan_shallow |
qwen3:8b |
Quick plan generation |
execute_editor |
qwen2.5-coder:14b |
Code execution / scaffolding |
embeddings |
qwen3-embedding:4b |
Source diversity ranking |
The parallel_agents setting in the research pool defaults to 2 to stay within 8 GB VRAM. The 14B synthesis model is only used when the skeptic pass flags issues — it does not run on every forage.
SourceCode/tui/indicator_phrases.py contains all the phrase tuples shown in the thinking indicator. Each task type has 5 phrases that cycle every 5–7 seconds. Edit freely — change wording, remove phrases, add task types.
FORAGE_PHRASES = (
"foraging",
"on the trail",
"digging in",
"casting the net",
"running it down",
)Interval bounds are PHRASE_INTERVAL_MIN / PHRASE_INTERVAL_MAX at the bottom of the file.
Projects/
<slug>/
research_summaries/ # Synthesis output, timestamped *.md
research_raw/ # Full agent findings, timestamped *.md
research_web_sources/ # Web source records
plan/ # Generated plans
deliverables/ # Build output
implementation/ # Scaffolded code
Runtime/
conversations/ # Per-project conversation history
projects/ # Project metadata DB
memory/ # Project and topic memory
SourceCode/
tui/ # Textual TUI app and widgets
orchestrator/ # Main pipeline and Reynard/DeepFox logic
agents_research/ # Research pool, synthesizer, source diversity
agents_make/ # Stack builder, scaffolding pools
shared_tools/ # Config, model routing, web research, stores
config.iniis gitignored — put local tokens and per-role model assignments here.config.ini.exampleis the tracked template; copy and edit.Projects/is gitignored per-project on first run.- Bots (Telegram / Discord / Slack) are optional:
pip install -r requirements-optional-bots.txt.
Service-Only Source-Available. See LICENSE and THIRD_PARTY_NOTICES.md.