AGI Core

A powerful AI-powered CLI assistant for software engineering. Chat with AI, execute tools, edit files, run commands, and automate complex development tasks - all from your terminal.

Features

- Interactive Chat - Conversational AI interface with streaming responses
- Tool Execution - Read/write/edit files, execute commands, search code
- Git Integration - Built-in git status, diff, commit, branch management
- Auto-Run Mode - AI autonomously completes multi-step tasks
- Session Persistence - Resume conversations across sessions
- Retry Logic - Automatic retry with exponential backoff for reliability

Installation

``bash


Install globally

npm install -g agi-core

Or install from source

git clone https://github.com/your-org/agi-core.git
cd agi-core
npm install
npm run build
npm link
`

Requirements: Node.js 20.0.0+

Quick Start

`bash


Set your API key

export OPENAI_API_KEY=your_key_here

Start interactive mode

agi

Quick one-shot query

agi -q "explain this error" < error.log
`

Commands

$3

| Command | Description |
|---------|-------------|
| /key | Set OpenAI API key |
| /model | Switch AI model (gpt-4o, gpt-4, etc.) |
| /clear | Clear conversation history |
| /history | View/manage conversation history |
| /c | Toggle auto-run mode |

$3

| Command | Description |
|---------|-------------|
| /help | Show all commands |
| /status | System status |
| /stats | Session statistics |
| /tools | List available AI tools |

$3

| Command | Description |
|---------|-------------|
| /toggle | Toggle stream/verbose/autosave |
| exit / quit / q | Exit CLI |

AI Tools

The AI has access to these tools for completing tasks:

$3


- read_file - Read file contents
- write_file - Create or overwrite files
- edit_file - Make precise text replacements
- list_directory - List directory contents
- search_files - Search by filename or content

$3

- grep_search - Regex pattern search
- find_definition - Find function/class definitions

$3

- execute_command - Run shell commands (with safety checks)

$3

- git_status - View modified/staged/untracked files
- git_diff - Show file changes
- git_log - View commit history
- git_commit - Stage and commit changes
- git_branch - Manage branches

$3

- web_search - Search the web
- fetch_url - Fetch URL content

Modes

$3

Displays AI responses character-by-character as they're generated.

$3

When enabled, the AI will automatically continue executing tasks until completion without waiting for user input. Toggle with /c.

$3

Shows additional details like response timing and tool result previews.

$3

Automatically saves conversation history after each exchange.

Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| Ctrl+C | Interrupt / Exit |
| Ctrl+D | Exit |
| Ctrl+L | Clear screen |
| ↑ / ↓ | Navigate command history |

Session Persistence

AGI Core automatically saves and restores your conversation:

- Sessions persist for 24 hours within the same workspace
- Use /history save to manually save
- Use /history clear to clear saved history
- Use /clear to start a fresh conversation

When resuming a session, you'll see:
`
↻ Resumed session with X previous messages
Use /clear to start fresh or /history to see details
`

Error Handling

AGI Core includes intelligent error handling:

- Automatic Retry - Retries on rate limits (429), server errors (5xx), and network issues
- Exponential Backoff - Waits progressively longer between retries
- Recovery Suggestions - Provides helpful tips when errors occur

Configuration

Configuration is stored in ~/.agi/:

`
~/.agi/
├── config.json # API keys, model preferences, mode settings
└── history.json # Saved conversation history
`

CLI Options

`bash
agi [options]

Options:
-v, --version Show version
-h, --help Show help
-q, --quick Quick mode (non-interactive single query)
--model Select model
--advanced Enable advanced features
`

Examples

$3


`
❯ read the main.ts file and fix any TypeScript errors
`

$3

`
❯ check git status and commit all changes with a descriptive message
`

$3

`
❯ find all files that import the UserService class
`

$3

`
❯ create a new React component called Button in src/components
`

$3

`
❯ run the tests and fix any failures
`

Development

`bash


Build

npm run build

Run tests

npm test

Run with coverage

npm run test:coverage

Clean build

npm run clean
`

Project Structure

`
src/
├── bin/
│ ├── agi.ts # Main CLI entry point
│ └── ui.ts # UI components and theming
├── core/
│ └── agi.ts # Core AGI framework
├── tools/
│ └── execution.ts # Command execution utilities
└── __tests__/ # Test suites
``

License

MIT

---

AGI Core - AI-powered development from your terminal