🚀 Astro Developer - AI-Powered CLI Assistant

An intelligent coding companion for modern developers.

Quick Start • Features • Commands • Configuration • Examples

⚠️ ALPHA RELEASE: This is an early version. Features and APIs can change at any time. Report issues.

🎉 What's New in v1.2.0

Enhanced Safety & Control:

• ✨ Create Tool - AI can now create new files with content, automatically creating parent directories as needed
• 🛡️ Confirmation System - All destructive operations (edit, execute, create, find/replace) now require confirmation before execution
• ⚙️ /autoapprove Command - Easily configure auto-approval settings per tool type (edit, execute, create, find_replace, all, none)
• 🔧 Fixed Execute Tool - Enhanced cross-platform compatibility, better error handling with stdout/stderr display, and proper exit codes
• 📦 Auto-Update Fix - Corrected package name to @novasuite/astro-developer for proper update checks

Better User Experience:

• Tab Autocomplete - Press Tab when typing / commands for instant suggestions
• Enhanced /status - Now displays all auto-approval settings with visual indicators (✓/✗)
• Smart Confirmations - Preview exactly what will happen before any destructive operation executes

✨ What is Astro Developer?

Astro Developer is an AI-powered CLI assistant that helps you read, edit, create, analyze, and debug code. It provides an interactive chat interface with intelligent tools that the AI can use to work with your codebase autonomously.

Perfect for:

• 🎯 Quick code edits and refactoring
• 🐛 Debugging and error analysis
• 📚 Understanding unfamiliar codebases
• ✨ Generating new files and boilerplate
• ⚡ Running commands and tests
• 📊 Analyzing project structure and metrics

🎯 Features

Core Capabilities

• 📖 Read Files - View files with syntax highlighting, line range filtering
• 🔍 Search - Find patterns and text across your codebase
• ✏️ Edit Files - Modify code with AI assistance and approval control
• ✨ Create Files - Generate new files with automatic directory creation
• ⚡ Execute Commands - Run terminal commands safely with confirmation
• 🔄 Find & Replace - Bulk text replacement with confirmation
• 📊 Analyze - Get codebase statistics and complexity metrics

Advanced Features

• 💬 Multi-turn Conversations - Context preserved across the chat session
• 🤔 AI Reasoning - Toggle visibility of AI thinking process with /toggle
• ⚡ Response Interruption - Press ESC to stop AI responses mid-stream
• 🛡️ Smart Confirmations - Preview and approve destructive operations before execution
• 🎯 Granular Auto-approval - Configure auto-approval per tool type with /autoapprove
• 🔄 Multiple AI Models - Switch between ModelA 9 Nano (fast) and ModelA 9 (powerful)
• ⚙️ Per-Directory Config - Settings stored in .astrodeveloper/config.json
• 📊 Rate Limiting - 50 requests per day during alpha
• 🔄 Auto-Updates - Automatic update checks with easy installation
• 🎨 Professional UI - Beautiful purple-themed terminal interface

🚀 Quick Start

1. Install

npm install -g @novasuite/astro-developer

2. Configure App Settings

astro-dev setup

Creates .astrodeveloper/config.json with your preferences (model, auto-approve, etc).

3. Launch Assistant

astro-dev assist

Or use individual commands:

astro-dev read src/app.js      # Read a file
astro-dev edit src/app.js      # Edit a file
astro-dev analyze src/         # Analyze codebase
astro-dev search "TODO"        # Search for text

4. Chat with AI

● "Read src/app.js and suggest optimizations"
[AI reads file and provides suggestions]

● /autoapprove edit
[Enable auto-approval for edits]

● "Refactor the UserAuth class to use async/await"
[AI makes changes with or without confirmation based on settings]

● /status
[Shows configuration and auto-approval settings]

📋 Available Commands

Interaction

| Command | Description | |---------|-------------| | /ask <question> | Ask the AI a specific question | | /debug [topic] | Get debugging assistance | | /explain <concept> | Explain programming concepts | | /practices [lang] | Show best practices (js, python, react, etc) |

Configuration

| Command | Description | |---------|-------------| | /model [key] | Switch AI models or list available | | /auto-approve | Toggle auto-approval for edits | | /autoapprove [setting] | Configure auto-approval per tool (edit, execute, create, find_replace, all, none) | | /toggle | Toggle AI thinking process visibility | | /status | Show current configuration |

Utilities

| Command | Description | |---------|-------------| | /readme | Show getting started guide | | /usage | Show daily API usage (50 requests/day during alpha) | | /update | Check for and install updates | | /help | Show all available commands | | /clear | Clear conversation history | | /exit | Exit the chat |

⌨️ Keyboard Shortcuts

| Keys | Action | |------|--------| | Ctrl+T | Toggle AI thinking process visibility | | Ctrl+A | Toggle auto-approval for file edits (legacy - use /autoapprove instead) | | ESC | Interrupt current AI response mid-stream | | Tab | Autocomplete commands (when typing /) |

⚙️ Configuration

Settings are stored in .astrodeveloper/config.json in your project directory.

Default Configuration

{
  "model": "modela-9-nano",
  "autoApproveEdits": false,
  "autoApproveExecute": false,
  "autoApproveCreate": false,
  "autoApproveFindReplace": false,
  "showConsideration": false,
  "conversationHistoryLimit": 20
}

Configuration Options

| Option | Values | Default | Description | |--------|--------|---------|-------------| | model | modela-9-nano, modela-9 | modela-9-nano | AI model to use | | autoApproveEdits | true, false | false | Auto-approve file edits | | autoApproveExecute | true, false | false | Auto-approve command execution | | autoApproveCreate | true, false | false | Auto-approve file creation | | autoApproveFindReplace | true, false | false | Auto-approve bulk find/replace | | showConsideration | true, false | false | Show AI thinking process | | conversationHistoryLimit | 5-50 | 20 | Messages to keep in context |

Reconfigure

astro-dev setup

🤖 AI Models

ModelA 9 Nano (Default)

• ✅ Fast response times
• ✅ Perfect for quick tasks and reviews
• ✅ Optimized for terminal usage
• ✅ Lower latency

ModelA 9

• ✅ More powerful analysis
• ✅ Better for complex refactoring
• ✅ Deeper understanding
• ✅ Larger context window

Switch anytime with:

/model modela-9
/model modela-9-nano

⬆️ Updates

Astro Developer includes an automatic update system that checks for new versions:

Auto-Update Notification

• Updates are checked every 24 hours (cached)
• When an update is available, you'll see a notification on startup
• Use /update command to check and install updates immediately

Updating

# Via the CLI
astro-dev update

# Or install directly
npm install -g astro-developer@latest

# Via /update command in chat
/update

Force Update Check

To bypass the 24-hour cache and check immediately:

astro-dev update --force

🛠️ AI Tools

The AI assistant can autonomously use these tools during conversations. You don't need to invoke them directly - just ask naturally and the AI will use the appropriate tools.

Available Tools

| Tool | Description | Requires Confirmation | |------|-------------|----------------------| | read | Read file contents with syntax highlighting | No | | search | Find text/patterns across your codebase | No | | list | List files and directories | No | | analyze | Get codebase statistics and metrics | No | | edit | Modify existing files | Yes (unless auto-approved) | | create | Create new files with content | Yes (unless auto-approved) | | execute | Run terminal commands | Yes (unless auto-approved) | | find_replace | Bulk text replacement across files | Yes (unless auto-approved) |

How Tools Work

The AI decides when to use tools based on your request:

You: "What's in the package.json file?"
AI: <uses read tool automatically>
     "Here's what I found in package.json: ..."

You: "Find all TODO comments"
AI: <uses search tool automatically>
     "I found 12 TODO comments across 5 files..."

You: "Create a new utils.js file with helper functions"
AI: <uses create tool, asks for confirmation>
     ⚠️  CONFIRMATION REQUIRED
     Create file "src/utils.js"?
     [Shows preview and asks approval]

💡 Examples

Code Review

You: "Review src/auth.js and suggest improvements"
AI: [Reads file, analyzes code, provides specific suggestions]

Debugging

You: "I'm getting a TypeError in UserComponent.js - can you help?"
AI: [Reads file, identifies issue, suggests fix]
You: "Yes, apply that fix"
AI: [Uses edit tool with confirmation]

Creating New Files

You: "Create a new API route for user registration at src/api/register.js"
AI: [Uses create tool, asks for confirmation with preview]

Refactoring

You: "/autoapprove edit"
     "Refactor all class components in src/components to use hooks"
AI: [Edits multiple files without confirmation per file]

Running Tests

You: "/autoapprove execute"
     "Run the test suite"
AI: [Executes npm test without confirmation]

Bulk Changes

You: "Replace all console.log with logger.info in the src directory"
AI: [Uses find_replace tool, shows count, asks for confirmation]

Quick Commands

/explain closure          # Get explanation of closures
/practices react          # Show React best practices
/status                   # View configuration
/usage                    # Check API usage (50/day limit)

🔒 Confirmation System

Manual Confirmation (Default)

All destructive operations require confirmation with detailed previews:

Edit Operations:

⚠️  CONFIRMATION REQUIRED

Edit file "src/app.js"?

File: src/app.js
Replacing:
const x = 1;

With:
const x = 2;

? Do you want to proceed? (y/N)

Execute Commands:

⚠️  CONFIRMATION REQUIRED

Execute command: "npm test"?

Command: npm test
Working directory: /path/to/project

? Do you want to proceed? (y/N)

Create Files:

⚠️  CONFIRMATION REQUIRED

Create file "src/utils.js"?

Content preview:
export const helper = () => {...}

Size: 150 bytes

? Do you want to proceed? (y/N)

Auto-Approval

Configure auto-approval per tool type:

# View current settings
/autoapprove

# Enable specific tool
/autoapprove edit      # Auto-approve edits
/autoapprove execute   # Auto-approve commands
/autoapprove create    # Auto-approve file creation
/autoapprove replace   # Auto-approve find/replace

# Enable/disable all
/autoapprove all       # Enable all
/autoapprove none      # Disable all

Or use the legacy toggle for edits only:

/auto-approve

⚡ Performance & Usage Tips

1. Enable auto-approval for trusted workflows

   /autoapprove all          # Enable all auto-approvals
   /autoapprove edit         # Just auto-approve edits

2. Use ModelA 9 Nano (default) for quick tasks

   • Faster responses, perfect for routine code changes
   • Switch to ModelA 9 for complex refactoring

3. Manage conversation history

   • Clear history when switching contexts: /clear
   • Default limit: 20 messages (configurable in .astrodeveloper/config.json)

4. Watch your daily usage

   • Alpha: 50 requests per day
   • Check remaining: /usage
   • Resets every 24 hours

📦 System Requirements

• Node.js: 14.0.0 or higher
• npm: 6.0.0 or higher
• Disk Space: ~50MB
• Internet: Required for AI features

🐛 Troubleshooting

Configuration not loading

Verify config file exists:

cat .astrodeveloper/config.json

Model not found

Check available models:

/model

Setup issues

Reconfigure from scratch:

astro-dev setup

Clear chat history

/clear

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

CC BY-NC-SA 4.0 - See LICENSE for details

🆘 Support & Bug Reports

Report Issues

Since Astro Developer is in ALPHA, we need your feedback!

• Report bugs: novasuite.one/report
• GitHub Issues: Report issues
• Discussions: Ask questions
• In-App: Run /readme for quick start guide

What to Include in Bug Reports

• Your astro-dev version (astro-dev --version)
• Operating system and Node.js version
• Steps to reproduce the issue
• Expected vs actual behavior

🎉 Credits

Built with ❤️ for developers who love their terminal

Built with:

• Commander.js - CLI framework
• Chalk - Terminal styling
• Inquirer.js - Interactive prompts
• Ora - Spinners and progress

v1.2.0 Alpha • Made for modern developers • Purple-themed 💜