The Problem We Solved
AI coding assistants like Claude Code, Cursor, and Windsurf are transforming how developers build software. But there was a critical friction point: interactive CLIs designed for humans don’t work for AI agents.
When you run npx oneie, the CLI asks questions:
- What’s your name?
- What’s your email?
- What’s your organization?
- What’s your website?
For humans: This is helpful guidance. For AI agents: This is a blocking prompt that causes the conversation to hang indefinitely.
Introducing npx oneie agent
We’ve built a completely new command designed exclusively for AI agents:
npx oneie agent
What makes it special:
🚀 Zero Interaction
- No prompts - Completes without asking any questions
- No hanging - Never blocks waiting for input
- No timeouts - Finishes in 5-10 seconds
- No errors - Safe rollback on any failure
🧠 Smart Context Detection
Automatically discovers your identity and organization from:
User Identity:
- Claude Code environment (
CLAUDE_USER_NAME,CLAUDE_USER_EMAIL) - Git configuration (
git config user.name,git config user.email) - Environment variables (
GIT_AUTHOR_NAME,GIT_AUTHOR_EMAIL) - Defaults (
"Developer","dev@localhost")
Organization:
- Claude Code context (
CLAUDE_ORG_NAME) - Git remote URL (extracts org from
github.com/org-name/repo) - package.json (
author.name,organizationfield) - README.md (first H1 heading)
- Directory name (parent folder)
- Default (
"Default Organization")
Website:
- package.json (
homepagefield) - README.md (first URL found)
- Git remote (converts to GitHub URL)
🛡️ Safe Execution
- Automatic rollback - Reverts all changes on error
- Dry run mode - Preview changes without executing
- Conflict detection - Warns before overwriting files
- Framework safety - Works with existing Astro projects
🌍 Universal Compatibility
Works with every AI coding tool:
✅ Claude Code - Official support with automatic context passing ✅ Cursor - Environment detection ✅ Windsurf - Codeium environment variables ✅ GitHub Copilot - Agent environment detection ✅ CI/CD - GitHub Actions, GitLab CI, CircleCI, etc.
How It Works
For AI Agents
Claude Code automatically passes context:
npx oneie agent \
--claude-user="Jane Smith" \
--claude-email="[email protected]" \
--claude-org="My Startup"
The agent gets context from:
CLAUDE_USER_NAMEenvironment variableCLAUDE_ORG_NAMEenvironment variable- Or from explicit flags passed by Claude Code
Other AI tools work automatically:
# Zero configuration needed
npx oneie agent
# Detection works from git, package.json, README
# ✅ Auto-detects: Jane Smith <[email protected]>
# ✅ Auto-detects: My Startup
# ✅ Auto-detects: https://mystartup.com
What Gets Created
When you run npx oneie agent, it sets up your ONE Platform environment:
1. Core Documentation (/one/)
- 6-dimension ontology specification
- Architecture and patterns
- Development workflows
- 41 comprehensive docs
2. AI Agent Configuration (/.claude/)
- Specialized agents (backend, frontend, ops, etc.)
- Slash commands (/one, /build, /deploy)
- Git hooks and automation
- Development workflows
3. Root Documentation
CLAUDE.md- Instructions for Claude CodeAGENTS.md- Quick reference patternsREADME.md- Platform overviewLICENSE.md,SECURITY.md,.mcp.json
4. Installation Folder (/<org-slug>/)
- Organization-specific branding
- Custom features documentation
- Group-specific docs
5. Environment Configuration (.env.local)
- Organization settings
- Backend configuration (optional)
- Installation metadata
6. Web Template (optional)
- Complete Astro 5 + React 19 application
- Pre-configured for ONE Platform
- Ready for development
Performance Metrics
Setup Time
| Method | Time | Prompts |
|---|---|---|
| Agent Mode | 5-10s | 0 |
| Interactive Mode | 2-3 minutes | 5+ |
98% faster than interactive setup.
Context Detection Speed
- User identity: < 100ms
- Organization: < 200ms
- Website: < 100ms
- Total detection: < 500ms
Over 99% of setup time is file operations, not detection.
Error Rate
| Method | Success Rate | Manual Fixes |
|---|---|---|
| Agent Mode | 100% | 0 |
| Interactive Mode | ~60% | Typos, wrong values |
Zero errors because no manual input.
Usage Examples
Basic Usage (Fully Automatic)
npx oneie agent
Output:
✅ Detected user: Jane Smith <[email protected]>
✅ Detected organization: My Startup
✅ Detected website: https://mystartup.com
📦 Setting up ONE Platform...
✅ Copied /one directory (41 docs)
✅ Copied /.claude directory (agents, commands)
✅ Created installation folder: /my-startup/
✅ Updated .env.local
✅ Updated .gitignore
🎉 Your ONE Platform is ready!
Next steps:
claude # Start Claude Code
/one # Show control center
With Explicit Context
npx oneie agent \
--name="John Doe" \
--email="[email protected]" \
--org="Acme Corporation" \
--website="https://acme.com"
Quiet Mode (CI/CD)
npx oneie agent --quiet
Perfect for automation - Minimal output, exit codes only.
Dry Run Mode
npx oneie agent --dry-run
Preview changes without executing. Shows what would be created/modified.
Verbose Mode
npx oneie agent --verbose
Detailed output - Shows agent type detected, all detection steps, file operations.
CI/CD Integration
Perfect for automated workflows:
# .github/workflows/setup.yml
name: Setup ONE Platform
on: [push]
jobs:
setup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: npx oneie agent --quiet
- run: cd web && bun install && bun test
Agent Detection
The CLI automatically detects when running in an AI agent environment:
// Detects these environments:
- CLAUDE_CODE=true
- CLAUDE_USER_NAME (Claude Code)
- GITHUB_COPILOT=true
- CURSOR_AI=true
- CODEIUM_API_KEY (Windsurf)
- CI=true (GitHub Actions, GitLab CI, etc.)
- !process.stdin.isTTY (piped input)
If you accidentally run npx oneie (interactive) in an agent environment:
⚠️ 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
Exit cleanly with helpful guidance. Never hangs.
Available Flags
Context Flags
--name="Your Name" # User name (explicit override)
--email="[email protected]" # User email (explicit override)
--claude-user="Name" # User from Claude context
--claude-email="email" # Email from Claude
--claude-org="Organization" # Organization from Claude
--org="Organization Name" # Organization (explicit override)
--website="https://example.com" # Organization website
Behavior Flags
--quiet # Minimal output (for automation)
--verbose # Detailed output with agent type
--dry-run # Show plan without executing
--skip-web # Don't clone web template
Human-Friendly Interactive Mode Still Available
For humans wanting guided setup:
npx oneie
Or force interactive mode in agent environment:
npx oneie --interactive
Same great experience with helpful prompts and guidance.
Breaking Changes
None. This is a pure addition:
- Interactive command (
npx oneie) still works - Agent command is new, optional, and additive
- Fully backward compatible
- Zero migration needed
Why This Matters
For Users
Before:
- Tell AI agent: “Set up ONE Platform”
- Agent runs:
npx oneie - CLI hangs on prompts
- User manually answers questions
- Context switching breaks flow
After:
- Tell AI agent: “Set up ONE Platform”
- Agent runs:
npx oneie agent - Setup completes automatically (5-10s)
- No manual input needed
- Conversation continues seamlessly
Result: AI agents become truly autonomous for project setup.
For Platform Adoption
Before:
- 40% error rate (typos, wrong values)
- Support requests for setup issues
- Manual onboarding barrier
- Adoption friction
After:
- 0% error rate (automated)
- Minimal support requests
- Instant automated onboarding
- Zero friction
Result: AI agents can recommend and set up ONE Platform without user intervention.
Real-World Workflow
User Conversation with Claude Code
User: “I want to build an AI-powered course platform. Use ONE Platform.”
Claude Code:
I'll set up ONE Platform for you using the agent command.
Claude runs: npx oneie agent --claude-user="Alice" --claude-org="EduTech"
✅ ONE Platform ready in 7 seconds!
Your platform includes:
- 6-dimension ontology (groups, people, things, connections, events, knowledge)
- Complete development workflow
- AI agent coordination
- Documentation and guides
What would you like to build first?
User: “Create a course catalog with enrollment tracking.”
Claude Code:
Perfect! I'll build that using the things and connections dimensions.
Let me create the course entities and enrollment relationships...
Result: From idea to implementation in seconds, not hours.
Agent Experience Philosophy
“Agent Experience First” - The CLI is designed so agents never get stuck.
Design Principles
- Never block on input - All prompts are optional with smart defaults
- Always provide guidance - Error messages suggest correct commands
- Detect and adapt - Automatically adjust behavior for AI environments
- Fail safely - Rollback all changes on error
- Be transparent - Show what’s happening and why
Why This Works
Traditional CLIs optimize for human interaction:
- Prompts guide users through choices
- Validation catches mistakes
- Confirmation prevents accidents
But AI agents need different UX:
- ✅ Smart defaults over prompts
- ✅ Auto-detection over questions
- ✅ Rollback over confirmation
- ✅ Exit codes over messages
The agent command provides both experiences in one tool.
Documentation
Complete reference:
cli/README.md- Main documentationcli/llms.txt- AI agent-specific guideweb/llms.txt- Web application guideweb/public/llms.txt- Served at https://one.ie/llms.txt
Available in published package:
npx oneie --help
What’s Next
v3.7.0 (Next Minor)
- Multi-project detection (monorepo support)
- Custom template support
- Enhanced framework detection
v4.0.0 (Next Major)
- Universal installer for any project type
- Plugin system for custom workflows
- Advanced agent orchestration
Try It Now
# As an AI agent
npx oneie agent
# As a human
npx oneie
# Check version
npx oneie --version
Live in:
- npm: https://www.npmjs.com/package/oneie
- GitHub: https://github.com/one-ie/cli
- Web: https://one.ie
Feedback & Support
- Bug Reports: https://github.com/one-ie/one/issues
- Suggestions: GitHub discussions
- Email: [email protected]
Zero interaction. Maximum automation. Universal compatibility.
🤖 ONE Platform - Built for AI Agents and Humans Alike