The Paradigm Shift
For decades, we’ve designed developer tools for humans:
- Interactive prompts guide users through choices
- Validation catches mistakes before they happen
- Confirmation dialogs prevent accidents
- Help text explains what each option means
This made sense. Humans need guidance, make typos, and appreciate safety rails.
But now we have a new user: AI coding assistants.
Claude Code, Cursor, Windsurf, GitHub Copilot, and dozens of other AI tools are becoming primary users of developer tools. And they have completely different needs.
The Problem: Tools Built for Humans Don’t Work for AI
Example 1: Interactive Prompts
Human experience:
$ npx create-react-app my-app
? What template do you want to use?
❯ Default
TypeScript
Minimal
✅ Human: Reads options, selects one, continues ❌ AI Agent: Sees prompt, doesn’t know how to respond, conversation hangs
Example 2: Confirmation Dialogs
Human experience:
$ rm -rf node_modules/
Are you sure? (y/n)
✅ Human: Considers consequences, confirms or cancels ❌ AI Agent: Can’t respond to stdin, blocks indefinitely
Example 3: Error Messages for Humans
Human experience:
$ npx oneie
Error: Git not configured
✅ Human: Understands what “git not configured” means ❌ AI Agent: Unclear what to do next, guesses wrong command
The Solution: Agent Experience First
Core insight: If you design for AI agents first, humans benefit too.
Principle 1: Never Block on Input
Bad (Human-First):
const name = await prompt("What's your name?");
const email = await prompt("What's your email?");
Good (Agent-First):
const name = detectUserName() || getCliArg("--name") || "Developer";
const email = detectUserEmail() || getCliArg("--email") || "dev@localhost";
Result:
- ✅ AI agents never block
- ✅ Humans can use
--nameand--emailflags for scripting - ✅ Both benefit from smart defaults
Principle 2: Provide Multiple Input Methods
Bad (Human-First):
# Only interactive mode
npx oneie
Good (Agent-First):
# Option 1: Interactive (humans)
npx oneie
# Option 2: Non-interactive (agents)
npx oneie agent
# Option 3: Explicit flags (both)
npx oneie agent --name="Alice" --org="Acme"
# Option 4: Environment variables (CI/CD)
CLAUDE_USER_NAME="Alice" npx oneie agent
Result:
- ✅ AI agents use non-interactive mode
- ✅ Humans use interactive mode or flags
- ✅ CI/CD uses environment variables
- ✅ All use the same underlying tool
Principle 3: Smart Defaults Over Prompts
Bad (Human-First):
if (!organization) {
throw new Error("Organization required. Please provide --org flag.");
}
Good (Agent-First):
const organization =
getCliArg("--org") ||
detectFromGitRemote() ||
detectFromPackageJson() ||
detectFromDirectory() ||
"Default Organization";
Result:
- ✅ AI agents never fail due to missing input
- ✅ Humans don’t need to remember all flags
- ✅ Both can override with explicit values
Principle 4: Helpful Error Messages
Bad (Human-First):
Error: Command failed
Good (Agent-First):
⚠️ Agent environment detected!
Did you mean to run: npx oneie agent
The interactive command requires manual input.
For AI agents and automation, use: npx oneie agent
Run with --help for more information.
Result:
- ✅ AI agents know exactly what command to use
- ✅ Humans understand the distinction
- ✅ Both get actionable guidance
Principle 5: Detect and Adapt
Bad (Human-First):
// Always use interactive mode
function setup() {
await askQuestions();
}
Good (Agent-First):
function setup() {
if (isAgentEnvironment()) {
return runAgentMode(); // Zero interaction
} else {
return runInteractiveMode(); // Guided prompts
}
}
Result:
- ✅ AI agents get automatic agent mode
- ✅ Humans get interactive mode
- ✅ Both get optimal experience for their context
Real-World Example: npx oneie agent
Let’s trace through how these principles manifest in ONE Platform’s CLI.
The Old Way (Human-First)
$ npx oneie
Welcome to ONE Platform! Let's set up your project.
? What's your name? █
If Claude Code runs this:
- Sees prompt
- Can’t provide stdin input
- Conversation blocks
- User has to manually intervene
- Failed automation
The New Way (Agent-First)
# Claude Code runs this:
$ npx oneie agent
🤖 Agent environment detected: Claude Code
✅ Detected user: Alice Johnson <[email protected]>
✅ Detected organization: TechStartup Inc
✅ Detected website: https://techstartup.com
📦 Setting up ONE Platform...
✅ Your ONE Platform is ready! (6.3s)
Next steps:
claude # Start Claude Code
/one # Show control center
What happened:
- ✅ Detected agent environment (CLAUDE_CODE=true)
- ✅ Auto-detected user from CLAUDE_USER_NAME
- ✅ Auto-detected org from CLAUDE_ORG_NAME
- ✅ Completed without any prompts
- ✅ Successful automation
If a human runs it:
$ npx oneie
Welcome to ONE Platform! Let's set up your project.
? What's your name? (Alice Johnson) █
Still works perfectly! But now humans can also use the agent mode:
$ npx oneie agent
Result: Same fast, automated setup that agents get.
Why This Matters
1. AI Agents Are Becoming Primary Users
GitHub Copilot: 1.8M+ developers (as of 2024) Cursor: 500K+ developers Claude Code: Growing rapidly
Projection: By 2026, more developers will use AI coding assistants than not.
2. Agent Workflows Are Fundamentally Different
Human workflow:
1. Read documentation
2. Understand options
3. Make informed choices
4. Run commands with selected options
Agent workflow:
1. User describes intent ("set up project")
2. Agent infers correct command
3. Agent runs command with smart defaults
4. Command completes without interaction
Key difference: Agents infer intent, humans specify intent.
3. Interactive CLIs Break Agent Autonomy
User: “Claude, set up ONE Platform for this project.”
Claude (with traditional CLI):
I'll run npx oneie to set it up.
*runs command*
The command is waiting for input. What's your name?
User: “Alice Johnson”
Claude:
*manually types name*
What's your email?
User: “[email protected]”
Repeat 5 more times…
Result: Agent couldn’t complete task autonomously. User experience degraded.
Claude (with agent-first CLI):
I'll set up ONE Platform using the agent command.
*runs: npx oneie agent*
✅ Done! Your ONE Platform is ready.
I detected your identity from git and Claude context.
What would you like to build?
Result: Agent completed task autonomously. User experience enhanced.
The Agent Experience Design Framework
Step 1: Identify Interactive Points
Audit your CLI:
- Where does it wait for user input?
- What prompts does it show?
- What confirmations does it require?
For each interaction:
- Can it be auto-detected?
- Can it have a smart default?
- Can it be provided via flag/env var?
Step 2: Provide Non-Interactive Mode
Create explicit agent mode:
your-cli agent # Non-interactive, auto-detects context
Or detection-based:
if (isAgentEnvironment()) {
runNonInteractive();
} else {
runInteractive();
}
Step 3: Implement Smart Detection
Multi-source priority chain:
- Explicit flags (—name, —email)
- Environment variables (AGENT_USER_NAME)
- Config files (.yourrc)
- Git configuration
- Project metadata (package.json)
- Safe defaults
Always succeeds, never blocks.
Step 4: Add Agent-Friendly Error Messages
Traditional error:
Error: Missing required parameter: --org
Agent-friendly error:
⚠️ Organization not detected
Auto-detection tried:
✗ Git remote: Not a git repository
✗ package.json: File not found
✗ Directory name: Using current directory
Using default: "Default Organization"
To override: your-cli --org="Your Organization"
Shows what was tried, what was chosen, how to fix.
Step 5: Test with Actual AI Agents
Don’t assume - verify:
# Test with Claude Code
claude "Set up my project with your-cli"
# Test with non-TTY
echo "" | your-cli
# Test with CI
CI=true your-cli
Ensure zero hangs, zero errors, zero manual intervention.
The Broader Impact
Impact 1: CLIs Become Autonomous
Before: CLIs required human in the loop After: CLIs complete autonomously when run by agents
Result: AI agents can truly automate workflows end-to-end.
Impact 2: Humans Get Better Tools Too
Benefits humans get from agent-first design:
- 🚀 Faster scripting - No interactive prompts to bypass
- 🔧 Better automation - Environment variables and flags work
- 📖 Clearer documentation - Explicit modes and options
- ⚡ Smarter defaults - Less manual configuration needed
Example: Human developers using ONE Platform can now run:
npx oneie agent
And get instant setup without answering 5+ questions. That’s better UX.
Impact 3: New Tool Categories Emerge
Tools that wouldn’t exist without agent-first design:
- Autonomous setup tools - Zero-config project initialization
- Agent orchestration tools - Coordinate multiple AI agents
- Context-aware tools - Adapt based on environment detection
- Self-healing tools - Detect and fix issues automatically
ONE Platform’s AI specialists are an example - they wouldn’t work without agent-first CLI design.
Common Objections
”But humans need guidance!”
Answer: Provide both modes.
# Guided mode for humans
your-cli
# Autonomous mode for agents
your-cli agent
Best of both worlds.
”But auto-detection might guess wrong!”
Answer: Explicit flags always override detection.
# Auto-detect (usually correct)
your-cli agent
# Override if needed (100% correct)
your-cli agent --name="Correct Name" --org="Correct Org"
Detection is a helper, not a dictator.
”But this is more code to maintain!”
Answer: Shared implementation.
// Common logic
function setup(options: Options) {
const context = detectContext(options);
return install(context);
}
// Interactive wrapper
async function runInteractive() {
const options = await askQuestions();
return setup(options);
}
// Agent wrapper
async function runAgent() {
const options = detectOptions();
return setup(options);
}
Core logic is identical. Only input gathering differs.
”But not all tools can auto-detect!”
Answer: Use progressive defaults.
// Can't detect? Use smart default
const region = detectRegion() || "us-east-1";
// Critical config? Ask human, tell agent
if (isAgentEnvironment()) {
console.log("Using default region: us-east-1");
console.log("Override with: --region=<region>");
} else {
region = await prompt("Select region:", ["us-east-1", ...]);
}
Agents get defaults + override instructions. Humans get prompts.
The Future: Agent-First Everything
CLIs (Now)
- npx oneie agent ✅
- npm, yarn, pnpm (coming soon)
- git, docker, kubectl (next wave)
APIs (Soon)
- Traditional: POST /users with full payload
- Agent-first: POST /users/infer (API detects and fills missing fields)
Web UIs (Later)
- Traditional: Multi-step forms
- Agent-first: Natural language + smart forms (agent fills 80%, human tweaks 20%)
Operating Systems (Future)
- Traditional: GUI dialogs
- Agent-first: Intent-based commands (OS infers and executes)
Practical Guidelines
For CLI Authors
- ✅ Add non-interactive mode (
--yes,--agent, or auto-detect) - ✅ Implement smart defaults (multi-source detection)
- ✅ Provide override flags (explicit always wins)
- ✅ Test with AI agents (Claude Code, Cursor)
- ✅ Document both modes (humans AND agents)
For AI Agent Developers
- ✅ Check for agent mode before running CLI
- ✅ Pass context explicitly (env vars, flags)
- ✅ Handle both modes (interactive and agent)
- ✅ Parse helpful errors (suggest correct command)
- ✅ Fail gracefully (don’t let CLI block conversation)
For Users
- ✅ Use agent mode when available (faster, fewer errors)
- ✅ Override when needed (detection isn’t perfect)
- ✅ Report hangs (help improve tools)
- ✅ Share workflows (help community learn)
Real-World Success Metrics
ONE Platform CLI
Before agent-first design:
- 40% error rate (manual input mistakes)
- 2-3 minute average setup time
- 60% of AI agent attempts failed
- High support burden
After agent-first design:
- 0% error rate (automated detection)
- 5-10 second average setup time
- 100% of AI agent attempts succeed
- Minimal support burden
Result:
- 98% faster setup
- 100% success rate for agents
- Zero support requests for setup issues
Call to Action
For tool authors:
- Review your CLI for agent compatibility
- Add agent mode (or auto-detect)
- Test with Claude Code, Cursor, Windsurf
- Document both modes clearly
For AI companies:
- Add agent detection to your tools
- Pass user context to CLIs
- Handle both interactive and non-interactive modes
- Contribute agent support to open source tools
For the community:
- Demand agent-first design
- Contribute agent mode PRs to popular tools
- Share agent workflows
- Help document best practices
Conclusion
Agent Experience First isn’t about replacing humans.
It’s about recognizing that AI agents are users too - and when you design for them, everyone benefits.
Interactive CLIs for humans. Autonomous CLIs for agents. Smart defaults for both.
That’s the future of developer tooling.
ONE Platform leads the way with npx oneie agent - the first major CLI designed agent-first from day one.
Try it:
npx oneie agent
See the philosophy in action.
Agent Experience First. Better tools for everyone.
🤖 ONE Platform - Built for the AI Age