Newa Flux

5 agents + 22 commands + MCP-backed evidence research + RTK-lite hooks. Faster, cheaper, more flexible.

A multi-agent workflow framework for Claude Code that keeps the benefits of parallel research, clean context, and structured handoffs without the complexity of heavyweight orchestration.

| | Complex Frameworks | Newa Flux | |---|---|---| | Commands | 30+ | 22 | | Agents | 10+ | 5 | | Config files | Many | 0 | | CLI tools | Yes | 0 | | Total files | ~100+ | ~37 |

Install

npx newaflux

Options:

npx newaflux --global     # All projects (default)
npx newaflux --local      # Current project only
npx newaflux --no-hooks   # Skip token-saving hooks
npx newaflux --with-rtk   # Detect RTK, skip bash-rewrite hook (keep others)
npx newaflux --uninstall  # Remove

Commands

Core Commands (11)

| Command | What it does | |---------|-------------| | /fluxn:init | Map your project with 4 parallel researchers -> PROJECT.md | | /fluxn:research <task> | Research with 4 focused agents using context7 + octocode + evidence tracking | | /fluxn:brainstorm | (new) Optional 9-step spec brainstorm between research and plan | | /fluxn:plan | Synthesize research (and optional spec) into phased plan with pre-mortem + falsifiable criteria | | /fluxn:execute [phase] | Execute phases with atomic commits | | /fluxn:verify | Read-only verification of implementation vs plan | | /fluxn:go <task> | Research + (optional brainstorm) + Plan in one shot | | /fluxn:language <code> | Set output language for all user-facing messages | | /fluxn:debug <bug> | Investigate and fix bugs with scientific debugging | | /fluxn:doctor | (new) Check MCP servers (context7, octocode-mcp) and write status cache | | /fluxn:mcp-setup | (new) Print copy-paste install snippets for required MCP servers |

Quick Commands (11)

| Command | What it does | |---------|-------------| | /fluxn:quick-search <task> | Lightweight research with 1 agent (max 1 context7 lookup, ≤80 lines, @evidence inline) | | /fluxn:quick-plan <task> | 1-5 task plan inline with lite Pre-mortem and falsifiable Done When | | /fluxn:visual-debug <bug> | Debug with Playwright screenshots + console logs | | /fluxn:status | One-glance project state table (no file write) | | /fluxn:todo [title] | Capture a todo from conversation | | /fluxn:summary | TL;DR of current research or latest milestone | | /fluxn:save-context [note] | Compress session to digest, then /clear safely | | /fluxn:resume [session] | Restore context after /clear | | /fluxn:skip-perms | Print/persist --dangerously-skip-permissions | | /fluxn:preview <task> | Generate interactive visual HTML preview with drag/resize/color editor | | /fluxn:savings | Token savings report from hooks |

Workflow

/fluxn:init          -> Maps your project (run once)
/fluxn:go <task>     -> Research + Plan (or run separately)
/fluxn:execute all   -> Execute all phases
/fluxn:verify        -> Verify everything works

Or step by step:

/fluxn:init
/fluxn:research fix the auth bug
/fluxn:plan
/fluxn:execute 1
/fluxn:execute 2
/fluxn:verify

Features

Required MCP Servers (v2.3+)

Newa Flux uses two MCP servers for evidence-backed research:

• context7 (Upstash) — versioned official documentation lookup. Free tier: 1k requests/month.
• octocode-mcp (bgauryy) — semantic code search across GitHub + LSP for current repo. Requires GITHUB_TOKEN.

After installing Newa Flux, run:

/fluxn:mcp-setup     # Print install instructions (uses -s user for global scope)
/fluxn:doctor        # Verify both are reachable

The setup snippets use -s user so the MCPs are installed globally (available in all your projects). Run once, never again.

If MCPs are missing, research degrades to WebSearch automatically with a yellow warning. Newa Flux never blocks on missing MCPs — it just declares MCP mode: degraded — websearch only in the research output. Every workflow command (init, research, brainstorm, plan, execute, verify, go, debug, visual-debug, quick-search, quick-plan) prints a one-time reminder on startup if the MCPs aren't set up yet.

Evidence Tracking

Every research finding includes an @evidence: tag pointing to the exact source:

• File line — @evidence: src/auth/login.ts:23
• Doc snippet — @evidence: context7:///facebook/react/19.2#hooks-rules
• Code result — @evidence: octocode://expressjs/express:lib/router.js#L42
• URL — @evidence: https://nextjs.org/docs/middleware

Findings without @evidence: are dropped before plan synthesis. Load-bearing claims require ≥2 independent sources OR an explicit @confidence: low annotation. This eliminates speculation in your plans.

Plans now include ## Pre-mortem and ## Falsifiable Completion Criteria sections. Every "done when" line must be a runnable command or grep-checkable assertion. Vague language like should, ensure, properly, appropriately, fast enough is rejected by an inline self-review pass.

Optional Brainstorm Step

For ambiguous tasks, run /fluxn:brainstorm between research and plan. It produces .fluxn/brainstorm/SPEC.md with:

• 2-3 alternative approaches (each with trade-offs and evidence base from the Evidence Index)
• Pre-mortem (failure modes ranked by likelihood × impact)
• Sectional design (data model, interfaces, file-level changes, test strategy, rollback plan)
• Falsifiable completion criteria

When SPEC.md exists and is approved, /fluxn:plan treats it as authoritative scope and lifts the pre-mortem + criteria verbatim. Without SPEC.md, the plan generates them inline.

The brainstorm flow follows the obra/superpowers pattern: 9 steps, one clarifying question per call (not batched), section-by-section design review.

Token-Saving Hooks

Newa Flux includes 4 pre-tool-use hooks that reduce token consumption by 30-60% on common operations. They are installed by default with npx newaflux.

| Hook | What it does | |------|-------------| | bash-rewrite | Rewrites commands for compact output (git status --short, git log --oneline -20) | | read-cap | Caps file reads at 500 lines if no limit is set | | grep-cap | Caps grep content output at 250 lines if no head_limit is set | | session-context | Injects .fluxn/STATE.md summary on session start |

Kill switch -- disable all hooks instantly:

export NEWAFLUX_HOOKS=off   # Bash/Zsh
$env:NEWAFLUX_HOOKS = "off" # PowerShell

RTK compatibility -- if you use RTK (Rust Token Killer), install with --with-rtk to skip the bash-rewrite hook (RTK handles that). The other 3 hooks still install.

Quick Commands

For tasks that don't need the full research-plan-execute cycle:

• /fluxn:quick-search "how does auth work" -- single researcher, max 80 lines, immediate answer
• /fluxn:quick-plan "add dark mode" -- 1-5 task plan from PROJECT.md context, no agents
• /fluxn:status -- instant project overview, no file writes
• /fluxn:todo "remember to add rate limiting" -- capture mid-conversation for later
• /fluxn:summary -- executive summary of current state

Save & Resume Context

Long sessions eat tokens. The save/resume workflow lets you /clear safely:

1. /fluxn:save-context -- compresses the session into a digest file in .fluxn/sessions/
2. Type /clear to reset context
3. /fluxn:resume -- reads the latest digest, primes context, you're back

The digest includes: what you were working on, decisions made, files touched, and where you left off.

Skip Permissions

For workflows where permission prompts slow you down:

/fluxn:skip-perms

Prints the claude --dangerously-skip-permissions command and offers to write it to settings.local.json. The wrapper scripts (bin/claude-yolo.cmd and bin/claude-yolo.sh) also launch Claude Code in this mode.

Caveats: Only use in trusted projects. Never commit settings.local.json to git.

Language Support

Set a preferred language for all user-facing output:

/fluxn:language pt

Supports any valid language code. Internal workflow files remain in English.

Clarifying Questions

During research and debugging, the framework asks structured questions using Claude Code's AskUserQuestion tool. Instead of free-text prompts, you get selectable options. Keeps setup fast while capturing context agents need.

Milestone Archiving

When /fluxn:verify passes, the entire workflow is archived to .fluxn/milestones/YYYY-MM-DD-<slug>/ via the bin/archive-milestone.js helper. An append-only INDEX.md tracks all completed milestones.

Architecture

Core commands                    Agents (specialized workers)
+---------------------+         +----------------------+
| /fluxn:init         |-------->| fluxn-researcher (x4)|
| /fluxn:research     |-------->| fluxn-researcher (x4)|
| /fluxn:plan         | inline  |                      |
| /fluxn:execute      |-------->| fluxn-executor   (x1)|
| /fluxn:verify       |-------->| fluxn-verifier   (x1)|
| /fluxn:go           |-------->| researcher + inline  |
| /fluxn:language     | inline  |                      |
| /fluxn:debug        |-------->| fluxn-debugger   (x1)|
+---------------------+         +----------------------+

Quick commands
+---------------------+         +----------------------+
| /fluxn:quick-search |-------->| fluxn-researcher (x1)|
| /fluxn:quick-plan   | inline  |                      |
| /fluxn:visual-debug |-------->| fluxn-debugger   (x1)|
| /fluxn:preview      |-------->| fluxn-designer   (x1)|
| /fluxn:summary      |-------->| fluxn-researcher (x1)|
| /fluxn:status       | inline  |                      |
| /fluxn:todo         | inline  |                      |
| /fluxn:save-context | inline  |                      |
| /fluxn:resume       | inline  |                      |
| /fluxn:skip-perms   | inline  |                      |
| /fluxn:savings      | inline  |                      |
+---------------------+         +----------------------+

Agents

| Agent | Model | Role | |-------|-------|------| | fluxn-researcher | Haiku 4.5 | Explores codebase and web. Has WebSearch/WebFetch. | | fluxn-executor | Sonnet 4.6 | Implements one phase with atomic commits. Full edit access. | | fluxn-verifier | Haiku 4.5 | Read-only verification. Cannot modify code. | | fluxn-debugger | Sonnet 4.6 | Scientific bug investigator. Playwright support. | | fluxn-designer | Haiku 4.5 | Interactive HTML previews with drag/resize/color editing. Spawned by /fluxn:preview. |

Project Files

All workflow state lives in .fluxn/ at your project root:

.fluxn/
+-- PROJECT.md          # Project map (persistent)
+-- STATE.md            # Current workflow state
+-- config.md           # User preferences (language, etc.)
+-- MEMORY.md           # Session index (save-context/resume)
+-- research/           # Research findings
+-- PLAN.md             # Execution plan with phases
+-- phases/             # Phase completion reports
+-- quick/              # Quick plans (quick-plan)
+-- sessions/           # Session digests (save-context)
+-- todos/pending/      # Captured todos
+-- debug/              # Debug session files
+-- previews/           # Visual HTML previews (preview command)
+-- VERIFICATION.md     # Verification results
+-- MILESTONE.md        # Task summary for future sessions
+-- milestones/         # Archived milestones
    +-- INDEX.md        # Append-only milestone index
    +-- YYYY-MM-DD-slug/  # One folder per completed task

Installation Structure

~/.claude/                      # (or ./.claude/ for --local)
+-- agents/                     # 5 agent definitions
|   +-- refs/                   # 5 reference files (debugger refs + preview-editor.js)
+-- commands/fluxn/             # 19 command files
+-- bin/                        # Wrapper scripts + archive helper
+-- newaflux-hooks/             # 4 hook scripts + rules.json
+-- settings.json               # Permissions + hook config

Requirements

• Claude Code CLI
• Node.js >= 16

License

MIT