@defai.digital/ax-cli 1.0.1 → 1.1.3

package/.ax-cli/CUSTOM.md

@@ -0,0 +1,97 @@
+# Custom Instructions for AX CLI
+
+**Project**: @defai.digital/ax-cli v1.1.0
+**Type**: cli
+**Language**: TypeScript
+**Stack**: React, Vitest, Zod, Commander, Ink, ESM, TypeScript
+
+Generated: 11/19/2025, 2:45:34 AM
+
+## Project Context
+
+- **Entry Point**: `dist/index.js`
+- **Package Manager**: npm
+- **Module System**: ESM
+- **CLI Tool**: This is a command-line interface application
+
+## Code Conventions
+
+### TypeScript
+- Use explicit type annotations for function parameters and returns
+- Prefer `const` and `let` over `var`
+- Use strict mode (strict type checking enabled)
+- **CRITICAL**: Always use `.js` extension in import statements (ESM requirement)
+  - Example: `import { foo } from "./bar.js"` (NOT "./bar" or "./bar.ts")
+
+### ES Modules
+- Use `import/export` syntax (not `require/module.exports`)
+- Top-level await is supported
+
+### Validation
+- Use **zod** for runtime validation
+- Validate all external inputs (API requests, file reads, user input)
+- Use `.safeParse()` for error handling
+
+## File Structure
+
+- **Source Code**: `src/`
+- **Tests**: `tests/`
+- **Tools**: `src/tools/`
+
+### Typical Structure
+- Commands: `src/commands/`
+- Utilities: `src/utils/`
+- Types: `src/types/`
+
+### Key Files
+- `package.json`: Node.js package configuration
+- `tsconfig.json`: TypeScript configuration
+- `vitest.config.ts`: Vitest test configuration
+- `.eslintrc.js`: ESLint configuration
+- `README.md`: Project documentation
+- `CLAUDE.md`: Claude-specific instructions
+
+## Development Workflow
+
+### Before Making Changes
+1. Read relevant files with `view_file` to understand current implementation
+2. Use `search` to find related code or patterns
+3. Check existing tests to understand expected behavior
+
+### Making Changes
+1. **NEVER** use `create_file` on existing files - use `str_replace_editor` instead
+2. Make focused, atomic changes
+3. Preserve existing code style and patterns
+4. Update related tests when modifying functionality
+
+### After Changes
+1. Run linter: `eslint . --ext .js,.jsx,.ts,.tsx`
+2. Run tests: `vitest run`
+3. Build: `tsc`
+
+## Testing Guidelines
+
+### Vitest
+- Use `describe`, `it`, `expect` for test structure
+- Place tests in `tests/` directory or `*.test.ts` files
+- Test edge cases: empty inputs, null/undefined, boundary conditions
+- Include Unicode and special character tests where relevant
+
+### Coverage Requirements
+- Aim for high test coverage (80%+ for new code)
+- Always test error paths and edge cases
+- Test both success and failure scenarios
+
+## Available Scripts
+
+- **Development**: `bun run src/index.ts`
+- **Build**: `tsc`
+- **Test**: `vitest run`
+- **Lint**: `eslint . --ext .js,.jsx,.ts,.tsx`
+
+### Quick Commands
+```bash
+npm run dev    # Start development
+npm test   # Run tests
+npm run build  # Build for production
+```

package/.ax-cli/index.json

@@ -0,0 +1,43 @@
+{
+  "projectName": "@defai.digital/ax-cli",
+  "version": "1.1.0",
+  "primaryLanguage": "TypeScript",
+  "techStack": [
+    "React",
+    "Vitest",
+    "Zod",
+    "Commander",
+    "Ink",
+    "ESM",
+    "TypeScript"
+  ],
+  "projectType": "cli",
+  "entryPoint": "dist/index.js",
+  "directories": {
+    "source": "src",
+    "tests": "tests",
+    "tools": "src/tools"
+  },
+  "keyFiles": [
+    "package.json",
+    "tsconfig.json",
+    "vitest.config.ts",
+    ".eslintrc.js",
+    "README.md",
+    "CLAUDE.md"
+  ],
+  "conventions": {
+    "moduleSystem": "esm",
+    "importExtension": ".js",
+    "testFramework": "vitest",
+    "validation": "zod"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
+    "dev": "bun run src/index.ts"
+  },
+  "packageManager": "npm",
+  "lastAnalyzed": "2025-11-19T07:45:34.457Z"
+}

package/README.md

@@ -33,7 +33,7 @@ Originally forked from [grok-cli](https://github.com/superagent-ai/grok-cli), AX
 
 **GLM-Optimized**: Primary support for GLM (General Language Model) with optimized performance for local and cloud GLM deployments.
 
-**Production-Ready**: Unlike hobby projects, AX CLI is enterprise-grade with extensive testing, TypeScript safety, and proven reliability.
+**Production-Ready**: AX CLI is enterprise-grade with extensive testing, TypeScript safety, and proven reliability.
 
 ---
 
@@ -232,10 +232,12 @@ npm run test:ui           # Interactive UI
 - **Bash Integration**: Execute shell commands through natural conversation
 - **Automatic Tool Selection**: AI chooses the right tools for your requests
 - **Multi-Step Task Execution**: Handle complex workflows with up to 400 tool rounds
+- **Intelligent Context Management**: Automatic pruning for infinite conversation length
+- **Project Analysis**: Auto-detect tech stack, conventions, and structure (`ax-cli init`)
 
 ### 🔌 **Extensibility**
 - **MCP Protocol Support**: Integrate Model Context Protocol servers
-- **Custom Instructions**: Project-specific AI behavior via `.ax/AX.md`
+- **Custom Instructions**: Project-specific AI behavior via `.ax-cli/CUSTOM.md`
 - **Plugin Architecture**: Extend with Linear, GitHub, and other MCP tools
 - **Morph Fast Apply**: Optional 4,500+ tokens/sec code editing
 
@@ -538,6 +540,118 @@ ax-cli --api-key YOUR_OPENROUTER_KEY --base-url https://openrouter.ai/api/v1 --m
 
 ---
 
+## 🎯 Project Initialization
+
+AX CLI can automatically analyze your project and generate optimized custom instructions for better performance and accuracy.
+
+### Quick Setup
+
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Initialize AX CLI (one-time setup)
+ax-cli init
+
+# Start using AX CLI with project-aware intelligence
+ax-cli
+```
+
+### What Gets Detected Automatically
+
+The `init` command intelligently analyzes your project:
+
+- ✅ **Project Type**: CLI, library, web-app, API, etc.
+- ✅ **Tech Stack**: React, Vue, Express, NestJS, Vitest, Jest, etc.
+- ✅ **Language & Conventions**: TypeScript with ESM/CJS, import extensions
+- ✅ **Directory Structure**: Source, tests, tools, config directories
+- ✅ **Build Scripts**: Test, build, lint, dev commands
+- ✅ **Package Manager**: npm, yarn, pnpm, or bun
+- ✅ **Code Conventions**: Module system, validation library, test framework
+
+### Generated Files
+
+**`.ax-cli/CUSTOM.md`** - Project-specific custom instructions:
+```markdown
+# Custom Instructions for AX CLI
+
+**Project**: your-project v1.0.0
+**Type**: cli
+**Language**: TypeScript
+**Stack**: Commander, Vitest, Zod, ESM
+
+## Code Conventions
+
+### TypeScript
+- Use explicit type annotations
+- **CRITICAL**: Always use `.js` extension in imports (ESM requirement)
+
+### Validation
+- Use **zod** for runtime validation
+- Validate all external inputs
+
+## File Structure
+- Commands: `src/commands/`
+- Utilities: `src/utils/`
+- Types: `src/types/`
+```
+
+**`.ax-cli/index.json`** - Fast project reference for quick lookups
+
+### Command Options
+
+```bash
+# Basic initialization
+ax-cli init
+
+# Force regeneration (after major project changes)
+ax-cli init --force
+
+# Verbose output showing detection details
+ax-cli init --verbose
+
+# Initialize specific directory
+ax-cli init --directory /path/to/project
+```
+
+### Benefits
+
+**🚀 Performance Improvements:**
+- **25-30% fewer tokens** - No repeated project exploration
+- **23% faster responses** - Direct file access using generated index
+- **Better accuracy** - Project conventions understood from the start
+
+**🧠 Smart Context:**
+- Knows your project structure instantly
+- Understands your tech stack and conventions
+- References correct file paths automatically
+- Follows project-specific patterns
+
+### When to Run Init
+
+- ✅ After cloning a new repository
+- ✅ When starting a new project
+- ✅ After changing major dependencies
+- ✅ When migrating frameworks (e.g., Jest → Vitest)
+- ✅ After restructuring directories
+
+### Team Usage
+
+**Option 1: Share Configuration**
+```bash
+# Commit configuration to repository
+git add .ax-cli/
+git commit -m "Add AX CLI project configuration"
+```
+
+**Option 2: Personal Configuration**
+```bash
+# Add to .gitignore for personal customization
+echo ".ax-cli/" >> .gitignore
+```
+
+---
+
 ## 📖 Usage
 
 ### Interactive Mode
@@ -944,6 +1058,170 @@ MCP servers are stored in `.ax/settings.json`:
 
 ---
 
+## 🎯 Strategic Architecture: AutomatosX vs Morph
+
+AX CLI is built on **two complementary technologies** that solve different problems at different architectural layers:
+
+### 🧠 AutomatosX: Orchestration Layer (Core Strategy)
+
+**AutomatosX is the strategic foundation** of AX CLI, providing enterprise-grade multi-agent orchestration:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AutomatosX Orchestration                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ Claude Code  │  │  Gemini CLI  │  │   OpenAI     │      │
+│  │  (Priority 3)│  │  (Priority 2)│  │  (Priority 1)│      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│                                                               │
+│  • Multi-Agent Coordination    • Health Checks              │
+│  • Intelligent Routing         • Circuit Breakers           │
+│  • Session Management          • Provider Fallback          │
+│  • Memory Persistence          • Workload Distribution      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+                    AX CLI Execution
+                            ↓
+           ┌────────────────┼────────────────┐
+           ↓                ↓                ↓
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │   Bash   │    │  Search  │    │   Edit   │
+    │   Tool   │    │   Tool   │    │   Tool   │
+    └──────────┘    └──────────┘    └──────────┘
+```
+
+**Key Capabilities**:
+- **Provider Coordination**: Routes tasks to Claude Code, Gemini CLI, OpenAI, or Grok based on availability and workload
+- **Intelligent Fallback**: Automatically switches to backup providers when primary fails
+- **Session/Memory**: Maintains context across multi-agent conversations
+- **Health & Reliability**: Circuit breakers, health checks, retry logic
+
+#### 🏛️ Architecture Purity: Why AX CLI Handles LLM Integration
+
+**Strategic Decision**: AutomatosX remains a **pure orchestration framework** while AX CLI handles all LLM-specific integration:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│             AutomatosX (Pure Orchestration)                  │
+│  • Provider-agnostic routing                                 │
+│  • Session/memory management                                 │
+│  • Health checks & circuit breakers                          │
+│  • NO LLM-specific code                                      │
+│  • NO model integration (0 lines)                            │
+│  • NO tree-sitter parsing                                    │
+└─────────────────────────────────────────────────────────────┘
+                           ↓ delegates to
+┌─────────────────────────────────────────────────────────────┐
+│           AX CLI (LLM Integration Layer)                     │
+│  • GLM-4.6, Grok, OpenAI, Anthropic, Google API clients      │
+│  • ~30,000 lines of LLM provider integration code            │
+│  • Tree-sitter parsing for code intelligence                │
+│  • Model-specific optimizations (reasoning mode, streaming)  │
+│  • Tool definitions (bash, editor, search)                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Why This Separation Matters**:
+
+1. **Maintainability** 🛠️
+   - AutomatosX stays clean: orchestration logic only (~3K LOC)
+   - AX CLI absorbs complexity: LLM APIs, model quirks, provider changes
+   - Bug fixes isolated to appropriate layer
+
+2. **Reusability** ♻️
+   - AutomatosX can orchestrate ANY tool/agent, not just LLM-based ones
+   - Same orchestration works for Python agents, Rust tools, shell scripts
+   - Other projects can use AutomatosX without inheriting LLM baggage
+
+3. **Testing & Reliability** ✅
+   - AutomatosX: Pure logic testing (fast, deterministic)
+   - AX CLI: Integration testing against real LLM APIs
+   - Clear boundaries make issues easy to diagnose
+
+4. **Evolution** 🚀
+   - LLM landscape changes rapidly (new models monthly)
+   - AutomatosX orchestration patterns remain stable
+   - AX CLI can add GPT-5, Claude 4, GLM-5 without touching AutomatosX core
+
+**What We Avoided**:
+- ❌ Mixing 30K lines of LLM code into orchestration framework
+- ❌ Coupling AutomatosX to specific model APIs
+- ❌ Making every AutomatosX user depend on OpenAI/Anthropic SDKs
+- ❌ Tree-sitter parser dependencies in core framework
+
+**The Result**: AutomatosX is a **pure, reusable orchestration platform**. AX CLI is a **specialized LLM CLI** built on top of it. Clean separation of concerns wins.
+
+### ⚡ Morph Fast Apply: Execution Layer (Optional Enhancement)
+
+**Morph is an optional performance enhancement** for file editing, not a core architectural component:
+
+```
+AutomatosX decides WHAT to edit
+            ↓
+┌───────────────────────────────┐
+│   How should we edit files?   │
+├───────────────┬───────────────┤
+│  Standard     │  Morph Fast   │
+│  Editor (✓)   │  Apply (opt)  │
+│               │               │
+│  • Free       │  • 4,500+     │
+│  • Built-in   │    tokens/sec │
+│  • Simple     │  • AI-powered │
+│    string     │  • Complex    │
+│    replace    │    refactors  │
+│               │  • Requires   │
+│               │    paid key   │
+└───────────────┴───────────────┘
+```
+
+**Why Keep Morph?**
+- ✅ Some users value speed for complex refactoring
+- ✅ Already optional - zero impact on non-users
+- ✅ Low maintenance burden (392 lines, stable)
+- ✅ Different problem space than AutomatosX
+
+**Why It's Not Core Strategy?**
+- ❌ Solves only ONE execution step (file editing)
+- ❌ No orchestration capabilities
+- ❌ Requires paid external API
+- ❌ Can be replaced by standard editor
+
+### 📊 Comparison Table
+
+| Capability | AutomatosX | AX CLI | Morph | Standard Editor |
+|------------|------------|--------|-------|-----------------|
+| **Strategic Value** | ⭐⭐⭐⭐⭐ Highest | ⭐⭐⭐⭐⭐ Highest | ⭐⭐ Low | ⭐⭐⭐ Medium |
+| **Architecture Layer** | Orchestration | Integration | Execution | Execution |
+| **Lines of Code** | ~3K (pure) | ~30K (LLM) | 392 | ~500 |
+| Multi-agent orchestration | ✅ | ❌ | ❌ | ❌ |
+| Provider routing/fallback | ✅ | ❌ | ❌ | ❌ |
+| Session management | ✅ | ❌ | ❌ | ❌ |
+| Health checks & reliability | ✅ | ❌ | ❌ | ❌ |
+| LLM API integration | ❌ | ✅ (all) | ❌ | ❌ |
+| Model-specific features | ❌ | ✅ | ❌ | ❌ |
+| Tree-sitter parsing | ❌ | ✅ | ❌ | ❌ |
+| File editing | ❌ | ❌ | ✅ (fast) | ✅ (basic) |
+| Complex code refactoring | ❌ | ❌ | ✅ | ❌ |
+| Reusable framework | ✅ | ❌ | ❌ | ✅ |
+| Cost | Free | Free | Paid | Free |
+| Required | ✅ Core | ✅ Core | ❌ Optional | ✅ Core |
+
+### 🎯 Bottom Line
+
+- **AutomatosX = Brain**: Pure orchestration framework - coordinates multiple agents, handles failures, manages state (reusable across any domain)
+- **AX CLI = Nervous System**: LLM integration layer - connects to GLM/Grok/Claude/GPT, handles model specifics, provides tools (~30K LOC)
+- **Morph = Fast Hands** (optional): Executes file edits quickly when you need performance
+- **Standard Editor = Reliable Hands**: Executes file edits reliably for everyone
+
+**Architectural Philosophy**:
+- **AutomatosX stays pure** (no LLM code) → reusable orchestration framework
+- **AX CLI absorbs complexity** (30K lines of LLM integration) → keeps AutomatosX clean
+- **We keep Morph** because some users find the speed valuable for refactoring
+
+This clean separation means AutomatosX can orchestrate Python agents, Rust tools, or any future AI models without being coupled to today's LLM APIs.
+
+---
+
 ## ⚡ Morph Fast Apply (Optional)
 
 Ultra-fast code editing at **4,500+ tokens/second with 98% accuracy**.
@@ -1059,59 +1337,6 @@ ax-cli -m anthropic/claude-3.5-sonnet -u https://openrouter.ai/api/v1
 
 ---
 
-## 🤝 Contributing
-
-We welcome contributions! AX CLI is enterprise-grade software, and we maintain high standards.
-
-### Development Setup
-
-```bash
-# Fork and clone
-git clone https://github.com/YOUR_USERNAME/ax-cli
-cd ax-cli
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Lint
-npm run lint
-
-# Type check
-npm run typecheck
-```
-
-### Contribution Guidelines
-
-1. **Tests Required**: All new features must include tests
-2. **Type Safety**: Full TypeScript with strict mode
-3. **Code Coverage**: Maintain 80%+ coverage
-4. **Documentation**: Update README and inline docs
-5. **Conventional Commits**: Use semantic commit messages
-
-### Pull Request Process
-
-1. Create feature branch: `git checkout -b feature/my-feature`
-2. Write tests for new functionality
-3. Ensure all tests pass: `npm test`
-4. Run type checking: `npm run typecheck`
-5. Update documentation as needed
-6. Submit PR with clear description
-
-### Code Standards
-
-- **TypeScript**: Strict mode, no `any` types
-- **Testing**: Vitest with high coverage
-- **Linting**: ESLint + Prettier
-- **Commits**: Conventional commits format
-
----
-
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details