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)
``bash
# macOS
brew install sox

# Ubuntu/Debian
sudo apt-get install sox

# Windows
choco install sox
`
- OpenAI API key with Realtime API access

Installation

$3

`bash
npm install -g sona-ai-voice
`

$3

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

`bash


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):
`bash
sudo npm install -g sona-ai-voice
`

Setup

First time setup - enter your OpenAI API key:

`bash
sona setup
`

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

Usage

$3

`bash


Navigate to any project directory

cd /path/to/your-project

Start Sona (indexes current directory)

sona talk
`

$3

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

$3

`bash
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

$3


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).

$3

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

$3

Run sona setup to configure your OpenAI API key

$3

Make sure ~/.npm-global/bin (or your npm global bin path) is in your PATH. Check with:
`bash
npm config get prefix
which sona
`

$3

- 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/