Idea: Inverted Claude Code - Shell-First with AI Assist

[djdarcy]

Concept

Inverted Claude Code: A shell-first workflow where AI assistance is opt-in rather than the default.

Current Model (Claude Code)

• Every input goes to AI by default
• Use !command to bypass AI and run shell commands directly
• AI-centric with shell escape hatch

Proposed Model (Inverted)

• Every input goes to shell by default (pass-through mode)
• Use ~command #comment to invoke AI assistance
• Shell-centric with AI assist trigger

---

How It Would Work

Trigger Syntax

~command --partial-params #help me with XYZ

Components:

• ~ - AI assistance trigger (similar to existing ! for shell escape)
• command --partial-params - What the user knows/has so far
• #comment - Natural language description of what help is needed

Example Interactions

Example 1: Regex Help

$ ~grep -E #find all IP addresses in this log file

AI Output:

grep -E '([0-9]{1,3}\.){3}[0-9]{1,3}' /var/log/syslog

▼ Explanation
  Pattern breakdown:
  - ([0-9]{1,3}\.){3} - Matches three octets followed by dots
  - [0-9]{1,3} - Matches final octet
  Sources: regex101.com, GNU grep manual

Example 2: Complex Command Construction

$ ~ffmpeg -i input.mp4 #convert to gif, 10fps, 480px wide

AI Output:

ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1:flags=lanczos" -c:v gif output.gif

▼ Explanation
  - fps=10: Sets frame rate to 10fps
  - scale=480:-1: Width 480px, height auto
  - flags=lanczos: High-quality scaling
  Sources: FFmpeg documentation

---

Output Structure

1. Primary Output: The completed command on a new line, ready to execute
2. Foldable Explanation: Collapsible section with parameter explanations, reasoning, and sources
3. Script Option: For complex solutions, offer to save as reusable script in /usr/local/bin

---

Implementation Options

1. Claude Code Feature Request

Would require Anthropic to add a "shell mode" toggle with new trigger character.

2. OpenAI Codex (Open Source)

More feasible since Codex is open source - could fork and implement.

3. Standalone DazzleML Tool

Wrapper around existing shells that intercepts ~ trigger and queries AI API.

---

Why This Matters

For users who already know the shell well, the current AI-first model can feel like overhead. This inverted approach:

• Preserves muscle memory - Regular shell commands work normally
• AI when needed - Quick access to help with complex regex, obscure flags, etc.
• Learning aid - Explanations help users understand WHY, not just WHAT
• Documented reasoning - Sources let users verify and learn

---

Questions for Discussion

1. Would you use a shell-first AI assist mode?
2. Is ~ a good trigger character, or would something else work better?
3. Should this be a standalone tool or a feature request to Claude Code/Codex?
4. What other features would make this useful?

Looking forward to hearing thoughts!

[djdarcy]

Clarification: Two Modes, Not Pure Inversion

After more thought, the goal isn't to purely invert Claude Code, but rather to have two distinct modes that users can switch between:

Mode 1: Normal Claude Code (AI-First)

• Current behavior - every input goes to AI
• Use !command to escape to shell
• Best for: exploratory work, complex multi-step tasks, when you want AI guidance

Mode 2: Enhanced Shell (Shell-First)

• Every input goes directly to shell
• Use ~command #help to invoke AI assistance
• Best for: experienced users who know what they want, quick command sequences

---

The Vim Analogy

This is similar to Vim's modal editing:

Vim	Proposed Tool
Normal mode (Esc)	AI-First mode - AI interprets everything
Insert mode (i/a)	Shell-First mode - shell executes everything
Commands change meaning based on mode	! and ~ behavior depends on current mode

Just as Vim users switch between modes based on their current task, users could switch between AI-first and shell-first modes based on their workflow needs.

---

Open Questions

1. Mode switching: What should the keybinding be to toggle modes?

   • A slash command like /shellmode and /aimode?
   • A keyboard shortcut?
   • Something else?

2. Consistent trigger character: Should we use ! in both modes for consistency?

   • In AI mode: !command = escape to shell (current behavior)
   • In Shell mode: !command #help = invoke AI assistance

   Or keep them distinct (! vs ~) to make the current mode obvious?

3. Visual indicator: How should the user know which mode they're in?

   • Different prompt character?
   • Status bar indicator?
   • Color change?

---

This dual-mode approach preserves the full power of Claude Code while adding a streamlined workflow for users who primarily work in the shell but occasionally need AI help with complex commands.

[djdarcy]

Next Steps: Proof of Concept

We're exploring building a standalone proof-of-concept for this dual-mode shell concept. The working name is "aish" (AI-Assisted Interactive Shell).

The initial design thinking is documented in 2026-01-29__13-16-31__aish-dual-mode-shell-poc-design.md for future reference.

Once we have something working, we'll:

1. Share the PoC here for feedback
2. File a feature request at anthropics/claude-code referencing this discussion

Stay tuned!

[djdarcy]

Related Projects & Prior Art

Some existing CLI-based AI assistant approaches worth studying:

Microsoft AIShell

https://github.com/PowerShell/AIShell

Microsoft's AI-powered shell assistant. Similar concept to what we're proposing, though tightly integrated with PowerShell.

OpenAI Codex CLI

https://github.com/openai/codex

OpenAI's terminal-based coding agent. More similar to Claude Code (AI-first with shell escape) than our proposed shell-first approach.

Claude Code

https://claude.ai/code

Anthropic's CLI - the tool we're extending. AI-first paradigm with ! to escape to shell.

---

Vision Clarification: AISH as a Real Shell

The goal for AISH isn't just an AI wrapper - it should be a real shell that people could feasibly use as:

• Linux login shell - Replace bash/zsh as default
• Windows CMD replacement - Simpler than PowerShell, familiar syntax

Why not PowerShell?

PowerShell is overkill for most tasks and has confusing syntax. Most of the time we just want to:

• Execute commands as we historically have
• Use familiar CMD/BASH patterns
• Get AI help when needed, not by default

Design Principles

1. CMD + BASH compatibility - Familiar commands work as expected
2. Minimal overhead - Shell-first, AI on-demand (~command #help)
3. Cross-platform - Same experience on Windows/Linux/macOS
4. Gradual AI integration - Users opt-in to AI assistance per-command

This positions AISH as a practical daily-driver shell, not just a demo or wrapper.

---

See design doc: 2026-01-29__13-16-31__aish-dual-mode-shell-poc-design.md