Sona

Sona is an intelligent CLI AI agent that i am working on at ShadowLabs. I am building sona to be a great companion with a large context window and do multiple useful tasks with in the CLI using a highly effective conversational user interface.

• Visit our website for future updates: trysona.dev

Description

On the higher level, Sona is currently a read-only CLI companion with agent capabilities for indexing your root codebase, answering any questions you have about implementations and logic without opening your agent panel if you're vibe coding. We at ShadowLabs believe the next human-agent interaction is through voice conversations without the hassle of opening your agent panel and typing your thoughts as prompts. With Sona, everything is smooth and conversational. We plan to make Sona so much more with future package updates, stay tuned.

Features

• Realtime voice conversation with an amazing personalized and friendly agent behavior
• High codebase awareness where the agent is able to index your project and understands your code
• Particle GUI visual animation
• Secure personal API key based configuration for the user
• Highly trained voice conversation sessions architecture

Prerequisites

• Node.js >= 18.0.0
• sox (for audio capture/playback)

  # macOS
  brew install sox
    
  # Ubuntu/Debian
  sudo apt-get install sox
    
  # Windows
  choco install sox

• OpenAI API key with Realtime API access

Installation

Quick Install

npm install -g sona-ai-voice

Fix Permission Errors (macOS/Linux)

If you see EACCES: permission denied errors, configure npm to use a user-owned directory:

# 1. Create a directory for global packages
mkdir -p ~/.npm-global

# 2. Configure npm to use this directory
npm config set prefix '~/.npm-global'

# 3. Add to your PATH (choose your shell):
# For zsh (macOS default):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# For bash:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 4. Install Sona
npm install -g sona-ai-voice

# 5. Verify installation
sona --help

Alternative: Use sudo (not recommended):

sudo npm install -g sona-ai-voice

Setup

First time setup - enter your OpenAI API key:

sona setup

Your API key will be stored securely in ~/.sona/config with restricted file permissions.

Usage

Start a voice conversation

# Navigate to any project directory
cd /path/to/your-project

# Start Sona (indexes current directory)
sona talk

Options

sona talk              # Full experience with GUI
sona talk --no-gui     # Terminal only (no particle window)
sona talk --no-index   # Skip codebase indexing

Other commands

sona setup    # Configure API key
sona test     # Test API connection
sona logout   # Remove stored API key
sona --help   # Show all commands

How It Works

1. Indexing: When you run sona talk, it indexes the current directory's source files
2. Context: Sona understands your codebase structure and can answer questions about it
3. Voice: Uses OpenAI's Realtime API for natural voice conversation
4. Web Search: Can search the web for information it doesn't know

Example Conversations

• "What files are in this project?"
• "Explain how the authentication works"
• "What dependencies does this project use?"
• "Search for the latest React 19 features"

Security

• API keys are stored in ~/.sona/config with 600 permissions (owner-only)
• Keys are obfuscated (not plain text)
• Never committed to git (.env.local is gitignored)
• You can remove your key anytime with sona logout

Troubleshooting

"EACCES: permission denied" when installing

This happens because npm tries to install to /usr/local which requires admin access. Solution: Configure npm to use a user-owned directory (see Installation section above).

"sox not found"

Install sox: brew install sox (macOS) or apt-get install sox (Linux)

"API key required"

Run sona setup to configure your OpenAI API key

"sona: command not found"

Make sure ~/.npm-global/bin (or your npm global bin path) is in your PATH. Check with:

npm config get prefix
which sona

Sona not responding

• Check your microphone is working
• Speak clearly and close to the mic
• Try sona test to verify API connection

Development

For development, see the GitHub repository.

License

MIT

Author

Zeradam Fantaye

• GitHub: https://github.com/ZeradamK
• LinkedIn: https://www.linkedin.com/in/zeradamkiflefantaye/