This is a submission for the GitHub Copilot CLI Challenge
What I Built
I built NeuroMode CLI, a cognitive regulation layer for AI-assisted development workflows.
During my testing with GitHub Copilot CLI, I noticed a pattern: when we ask for something broad, the AI tends to expand even further. It delivers complete architecture, multiple decisions, a high level of abstraction, and many layers of information all at once.
This is technically impressive. But cognitively heavy.
For developers with focus difficulties, anxiety, depression, ASD, ADHD, low mental energy, or even beginners, this type of response can lead to paralysis rather than progress.
NeuroMode CLI proposes a simple, yet structural solution:
- Measure task complexity (Cognitive Friction Score)
- Detect high cognitive load levels
- Automatically activate a progressive decomposition mode
- Release only the next minimal executable step
- Control sequential advancement
- Classify command risk
- Suggest micro-prompts for Copilot
Instead of delivering an entire architecture, it forces incremental progression. This transforms the experience from:
I need to do all of this now.
To:
I just need to execute this next step.
NeuroMode does not replace Copilot.
It reorganizes how we interact with it.
Cognitive Friction Score
NeuroMode introduces a heuristic Friction Score inspired by Cognitive Load Theory and decision fatigue research.
The score estimates task complexity based on linguistic signals such as multiple action verbs, abstraction level, and ambiguity indicators. The purpose of this score is not to diagnose cognition, but to estimate task-induced cognitive demand before execution begins.
Theoretical Basis
The concept draws from:
- Cognitive Load Theory (Sweller, 1988)
- Executive Function research
- Task complexity modeling in software engineering
- Progressive disclosure design patterns
Cognitive Load Theory suggests that working memory capacity is limited. When instructional or problem-solving information exceeds that capacity, performance degrades. In AI-assisted development, large, multi-domain tasks often exceed that threshold.
NeuroMode attempts to approximate this threshold through a computational heuristic.
How the Score Is Calculated
The Cognitive Friction Score is computed using a weighted heuristic model:
1.Baseline Complexity
Word count of task description
2.Complexity Keywords Boost
Additional weight is added for high-abstraction or architecture-level keywords such as:
- scalable
- distributed
- microservices
- multi-tenant
- analytics
- dashboard
- authentication
- billing
- infrastructure
- enterprise
Each detected term increases the score.
3.Multi-Domain Scope Detection
Tasks that imply multiple subsystems (e.g., billing + authentication + analytics) accumulate higher friction.
Simplified Formula
CFS = WordCount
+ Σ (HighComplexityKeywordWeight)
+ MultiDomainScopeBoost
Example
(I employed ChatGPT to produce these examples)
Why Normalization Is Important
Without normalization, multi-domain tasks would inflate the score disproportionately. NeuroMode intentionally limits compounding boosts to:
- Keep the score interpretable
- Avoid artificial escalation
- Preserve threshold-based mode activation logic
The goal is not to exaggerate complexity, but to detect when progressive decomposition should be activated.
Example:
F = (RawScore / MaxExpectedScore) × 100
F = 48/60 x 100 = 80%
What the Score Triggers
When the Cognitive Friction Score crosses the defined threshold:
- High cognitive load is detected
- Progressive Decomposition Mode is activated
- Sequential execution is enforced
In this example:
CFS = 48 → Progressive Mode Activated
Demo
GitHub repo:
https://github.com/camilapydata/neuromode
Installation & Setup
# 1. Clone the repository
git clone https://github.com/yourusername/neuromode-cli.git
# 2. Enter the project directory
cd neuromode-cli
# 3. Install dependencies
npm install
# 4. Run NeuroMode
node neuromode.js
You will see:
Describe your task:
>
Requirements
- Node.js 18+
- npm 9+
- Terminal (PowerShell, Bash, zsh, etc.)
Check your version:
node -v
npm -v
Before vs After Example
Without NeuroMode CLI
Example showing what a command would look like without using the NeuroModeCLI.
See the video: https://drive.google.com/file/d/1r0clOrWYuwVkw_o0qdq7dEAZhLjTfy_u/view?usp=sharing
Copilot CLI response generates:
- Full architecture design
- Multiple subsystems
- Deep descriptions
- This results in cognitive fragmentation.
Now with NeuroMode CLI
Real CLI Execution Example
Here is NeuroMode running in Progressive Decomposition Mode:
Input:
Develop a scalable multi-tenant SaaS platform with authentication, billing, analytics and monitoring infrastructure
NeuroMode Output:
Cognitive Friction Score: 48
High cognitive load detected
Progressive Decomposition Mode activated
Sequential execution enforced (1/5 → 5/5)
What This Demonstrates
- This example shows that NeuroMode:
- Detects cognitive overload automatically
- Switches into adaptive task decomposition mode
- Enforces single-focus execution
- Prevents premature system-wide complexity
- Guides structured implementation
Instead of generating a full architectural blueprint, NeuroMode forces incremental execution. The developer only sees the next minimal executable unit. This prevents overload and reduces task initiation paralysis.
Future Work & Roadmap
NeuroMode CLI is a prototype with a clear evolution path:
- Adaptive thresholds based on user history
- Copilot wrapper integration
- IDE plugin support
- Presets for ADHD / Anxiety / Beginner
- Behavioral personalization profiles
- Empirical user studies
Limitations
- Heuristic-based (non-ML model)
- Language-dependent
- Prototype stage
- Not clinically validated
Tech Stack
- Node.js (v18+) – CLI runtime
- JavaScript (ES6+) – Modular cognitive regulation engine
- Readline API – Interactive command-line interface
- Heuristic Scoring Model – Cognitive Friction estimation
- Adaptive Threshold System – Automatic mode switching
- Sequential Execution Controller – Step-gated task progression
- GitHub Copilot CLI – AI behavior stress-testing & complexity validation
- Git + GitHub – Source control & distribution
- MIT License – Open-source compliance
My Experience with GitHub Copilot CLI
I used GitHub Copilot CLI throughout the entire development process of NeuroMode. I used Copilot CLI for:
- Refining the CLI architecture
- Adjusting modularization
- Improving file structure
- Suggesting incremental improvements to the workflow
- Simulating complex scenarios to test Cognitive Friction
Copilot produced detailed guidance, but also cognitive overload. NeuroMode’s job is not to suppress Copilot. It is to pace the output meaningfully.
I conducted an empirical stress test
I evaluated 20 complex prompts with Copilot CLI:
- 17/20 expanded beyond the original boundaries
- NeuroMode successfully decomposed and controlled all 17
During the process, I observed something fundamental:
When I asked for something broad, Copilot naturally expanded the scope even further.
This confirmed my initial hypothesis:
The AI is optimized for solution maximization, not for cognitive regulation. This realization became the center of the project. Copilot helped me structure the code. But it was the perceived cognitive friction during use that inspired NeuroMode. The project, therefore, is not a criticism of Copilot. It is a proposal for evolution:
An optional mode where the AI adapts to the developer's cognitive state.
Author
Camila Simões
Student - Federal University of Rio de Janeiro, Brazil
NeuroMode CLI is an experimental prototype exploring how AI tools can move beyond generation and begin regulating cognitive friction in developer workflows.
Top comments (0)