Betopia Agent

What is Betopia Agent?

Betopia Agent is an autonomous, terminal-based AI coding assistant that lives directly in your local development environment. Rather than copying and pasting code back and forth from a web browser, Betopia Agent can proactively explore your workspace, write code, edit files, and execute terminal commands on your behalf.

It leverages top-tier AI models (like GPT-5.4 and Claude Sonnet 4.6) to act as your personal pair-programmer, capable of understanding context and executing complex, multi-step engineering tasks autonomously.

What can you do with it?

• Generate Complete Projects: Ask the agent to build a React app, a Python script, or a full-stack web service from scratch. It will create all the necessary files and folders in your chosen directory.
• Refactor & Edit Code: Ask it to add a new feature, optimize a function, or fix a bug in your existing codebase. The agent will open the necessary files, read your code, and apply surgical edits.
• Run Terminal Commands: The agent can run unit tests, check Git statuses, or install missing NPM/Pip dependencies directly via your terminal.
• Navigate Your Workspace: By default, it operates wherever you launch it. You can dynamically navigate to any folder during a chat session using the /cd <path> command.
• Seamlessly Switch Models: Easily switch between OpenAI and Anthropic models on the fly using /model <model_name> depending on your specific task's reasoning requirements.
• Secure Configuration: Your API keys and model preferences are securely saved locally in ~/.betopia_agent_config.json.

Setup & Installation

Quick Install (Recommended)

# Install Betopia Agent globally via npm
npm install -g betopia-agent

# Run the agent from any directory
betopia-agent

That's it! The agent will work immediately.

Windows Users - Important!

If you get "betopia-agent is not recognized" after installation:

Option 1: Use npx (Simplest - No PATH setup needed)

npx betopia-agent

Option 2: Fix your PATH (Recommended for permanent use)

1. Find your npm global directory:

   npm prefix -g

   (Usually shows: C:\Users\YourName\AppData\Roaming\npm)

2. Add that directory to your Windows PATH:

   • Press Win + X → System → Advanced system settings
   • Environment Variables → Find "Path" → Edit
   • Add New → Paste the npm directory path
   • OK → Restart your command prompt

3. Test: betopia-agent

Option 3: Run our Windows Setup Helper

# Download from the repository and run:
windows-setup.bat

📖 Full Windows Troubleshooting Guide: See TROUBLESHOOTING.md

Prerequisites

Required:

• Node.js 14+ - Install from https://nodejs.org/ or via:

  • macOS: brew install node
  • Ubuntu/Debian: sudo apt-get install nodejs npm
  • Windows: Download installer from nodejs.org

• Python 3.8+ - Required for the agent to function (it's a Python application)

  • macOS: brew install python3
  • Ubuntu/Debian: sudo apt-get install python3 python3-pip
  • Windows: Download from https://www.python.org/

Python Dependencies:

• requests module - The agent will help you install this automatically when you first run it, or you can install manually:

  python3 -m pip install requests --user

How It Works

1. Installation: The npm package automatically sets up the betopia-agent command globally on your system
2. Auto-detection: The agent automatically finds Python if it's available, or uses fallback behavior
3. Works anywhere: Once installed, you can run betopia-agent from any directory in your terminal

Alternative Installation Methods

Use npx (No installation required):

npx betopia-agent

Install from source:

# Clone the repository
git clone https://github.com/Ahasun-h/betopia-terminal-agent.git
cd betopia-terminal-agent

# Install globally
npm install -g .

Windows users having trouble?

# Use npx without installing:
npx betopia-agent

# Or try npm exec:
npm exec -- betopia-agent

First Run

The first time you run betopia-agent, it will prompt you for your API key. Enter your Betopia API key to get started.

Configuration

API Key Setup

The first time you run betopia-agent, it will automatically prompt you to enter your API Key. If you ever need to change or update your API Key, you can do so directly within the agent chat:

You: /apikey YOUR_NEW_API_KEY_HERE

Example: /apikey sk_*****************************************

Changing the AI Model

The Betopia Agent supports multiple advanced AI models. By default, it uses gpt-5.4.

Available Models:

• gpt-5.4
• gpt-5.4-mini
• claude-sonnet-4-6
• claude-haiku-4-5

To switch models, type the following command inside the agent chat:

You: /model MODEL_NAME

Example: /model claude-sonnet-4-6

Your model preference and API key are securely saved in ~/.betopia_agent_config.json and will be remembered for future sessions.

Changing the Working Directory

If you want the agent to generate project files in a specific folder, you can change its active directory at any time without leaving the chat:

You: /cd /path/to/your/folder

The agent will instantly update its context to this new directory and create/read files from there!

Creating Standalone Executables (Optional)

If you want a single executable file that you can share or run without installing Python globally, you can use our build scripts:

• For Windows: Double-click build.bat
• For Mac/Linux: Run ./build.sh

The executable will be generated in the dist folder. You can move it anywhere on your system and run it directly.

Having Issues?

Windows Users

If you're getting "betopia-agent is not recognized" errors:

• 📖 Read our Windows Troubleshooting Guide
• 🔧 Run the Windows setup helper: windows-setup.bat
• 🚀 Quick fix: Use npx betopia-agent instead

Common Solutions

• Command not found: Make sure you installed globally: npm install -g betopia-agent
• PATH issues: Add npm directory to your system PATH (see TROUBLESHOOTING.md)
• Permission errors: Try running as administrator/sudo
• Node.js version: Ensure you have Node.js 14+

Still Need Help?

• 📋 Report issues: https://github.com/Ahasun-h/betopia-terminal-agent/issues
• 📧 Email support: [email protected]
• 🌐 Website: https://betopia.ai