Interactive CLI

Launch the buildwithnexus interactive shell to work with AI agents in real time.

Getting Started

buildwithnexus

This launches the main REPL where you can:

Describe tasks in natural language
Choose between PLAN, BUILD, and BRAINSTORM modes
See live agent activity streaming in real time

Workflow

1. Start the Shell

buildwithnexus

You'll see:

╔════════════════════════════════════════════════════════════╗
║        Nexus - Autonomous Agent Orchestration              ║
║        v0.8.5                                               ║
╚════════════════════════════════════════════════════════════╝

Welcome! Describe what you want the AI agents to do.
Type "exit" to quit.

📝 Task: _

2. Describe Your Task

Type what you want done:

📝 Task: Build a REST API for user authentication

3. Choose a Mode

The system suggests a mode (PLAN, BUILD, or BRAINSTORM):

Press Enter to use PLAN or choose a mode:
  [1] PLAN   design & break down steps
  [2] BUILD  execute with live streaming
  [3] BRAINSTORM  free-form explore & Q&A

Type your choice and press Enter.

4. Execute

The agents work on your task and stream results:

🎯 Plan Breakdown
├─────────────────────────────────────────────────────────┤
│  ○  Step 1: Design JWT token strategy                   │
│  ○  Step 2: Implement user registration endpoint       │
│  ○  Step 3: Implement login endpoint with token gen    │
│  ○  Step 4: Add refresh token mechanism                │
└─────────────────────────────────────────────────────────┘

Options: [Y] Execute  [e] Edit step  [n] Cancel

> _

Modes

PLAN Mode 🎯

Strategic task decomposition. The agents break down your request into concrete steps, which you can review and edit before execution.

BUILD Mode 🔨

Direct execution. Agents implement the task with live streaming of their progress, reasoning, and tool usage.

BRAINSTORM Mode 💡

Creative exploration with real-time streaming. For domain-specific or open-ended queries, the Chief of Staff thinks through the problem, showing you their reasoning as they go. You'll see:

💭 "Thinking..." indicator when processing
→ Thoughts and observations as they stream in
⚙️ Actions the agent is taking
Final analysis and recommendations

Perfect for questions like "How can I optimize my API performance?" or exploring ideas interactively.

Mode Switching

Use slash commands to change modes:

/switch     Switch to the next mode
/mode       Switch modes (same as /switch)

Example: While in PLAN mode, type /switch to move to BUILD.

Slash Commands

/brainstorm [idea]

Start a brainstorm session:

💬 You: How can I automate QA testing?

The system detects domain-specific keywords and asks clarifying questions:

1. Current Testing Setup - What testing framework are you using?
2. Coverage Goals - What's your target coverage percentage?
3. Timeline - Do you have a deadline for implementation?
4. Integration Scope - Should this integrate with CI/CD?

Then provides tailored recommendations based on your answers.

Full Command List

| Command | Description | |---------|-------------| | buildwithnexus | Launch interactive shell | | buildwithnexus run <task> | Run a task directly | | buildwithnexus da-init | Configure API keys | | buildwithnexus --version | Show version | | buildwithnexus --help | Show help |

Examples

Example 1: PLAN Mode

buildwithnexus

📝 Task: Create a user dashboard component

Press Enter to use PLAN or choose a mode:
  [1] PLAN   design & break down steps
  [2] BUILD  execute with live streaming
  [3] BRAINSTORM  free-form explore & Q&A
> 1

🎯 Plan Breakdown
├─────────────────────────────────────────────────────────┤
│  ○  Step 1: Design data model for user profile         │
│  ○  Step 2: Create React component structure           │
│  ○  Step 3: Add authentication checks                  │
│  ○  Step 4: Implement error handling                   │
└─────────────────────────────────────────────────────────┘

Options: [Y] Execute  [e] Edit step  [n] Cancel
> y

🔨 Executing...

Example 2: BRAINSTORM Mode

buildwithnexus

📝 Task: How can I speed up database queries?

Press Enter to use PLAN or choose a mode:
  [1] PLAN   design & break down steps
  [2] BUILD  execute with live streaming
  [3] BRAINSTORM  free-form explore & Q&A
> 3

💡 Thinking...

1. Current Database - What database system are you using?
2. Query Volume - How many queries per second?
3. Data Size - How large is your dataset?
4. Infrastructure - Are you running on cloud or on-premises?

💬 You: PostgreSQL, 1000 QPS, 500GB, cloud (AWS)

Based on your answers, here are tailored optimizations:
- Index creation strategy for 500GB PostgreSQL...

Tips

Edit steps in PLAN mode: Refine steps before execution to customize the plan
Clarify in BRAINSTORM mode: Ask follow-up questions to explore ideas interactively
Stream output: All modes stream agent activity in real time - watch as they think and act
Real-time thinking: In BRAINSTORM mode, you'll see the agent's reasoning stream in as they think through your question
Exit anytime: Type "exit" or press Ctrl+C to quit

What You'll See

BRAINSTORM Mode Streaming

💭 Thinking...

→ First, I need to understand the current codebase architecture...
→ The main bottleneck appears to be in database query optimization...
⚙️  Analyzing caching strategies...
→ I recommend implementing Redis for session management...

[Full analysis with specific recommendations...]

Environment Variables

# Set API keys explicitly (overrides ~/.buildwithnexus/.env.keys)
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...

buildwithnexus

Troubleshooting

Backend connection failed

The CLI automatically starts the backend on first run. If it fails:

buildwithnexus da-init  # Reconfigure

Mode not responding

Press Ctrl+C to cancel and try again:

buildwithnexus

Slow streaming

This is normal - agents are thinking. The more complex the task, the longer it takes.