RESONANT Agent Docs

Install, configure, and master your local AI agent. You can read this directly or hand it to an LLM and say: "Walk me through this one step at a time."

← Back to home

Website: aware-nirvana-rwmb.here.now
GitHub: github.com/Ajenee7773/Resonant-Agent

🧞 What is RESONANT Agent?
RESONANT Agent is a local AI agent harness built on the Pi coding agent runtime. Pi is the engine. RESONANT is the identity, harness, room system, local UI, memory structure, skills, voice layer, Telegram option, heartbeat runner, and out-of-the-box experience. One computer. One operator. One local agent that wakes up with identity, memory, and the ability to grow with you.

Getting Started

Before installing, make sure you have:

Installation

macOS

cd ~
git clone https://github.com/Ajenee7773/Resonant-Agent.git
cd Resonant-Agent
chmod +x install.sh configure.sh start.sh ui.sh heartbeat-start.sh telegram-setup.sh telegram-start.sh
./install.sh
./configure.sh
./start.sh

If macOS says developer tools are missing, run xcode-select --install and retry.

Linux

cd ~
git clone https://github.com/Ajenee7773/Resonant-Agent.git
cd Resonant-Agent
chmod +x install.sh configure.sh start.sh ui.sh heartbeat-start.sh telegram-setup.sh telegram-start.sh
./install.sh
./configure.sh
./start.sh

Windows (PowerShell)

cd $env:USERPROFILE
git clone https://github.com/Ajenee7773/Resonant-Agent.git
cd Resonant-Agent
.\install.ps1
.\configure.ps1
.\start.ps1

PowerShell is recommended on Windows.

Public one-line install (after repo goes public):

curl -fsSL https://raw.githubusercontent.com/Ajenee7773/Resonant-Agent/main/install.sh | bash

Configuration

During configuration, RESONANT asks for a model mode:

Context Window

If your model supports a large context, enter it during configuration:

128000
200000
1000000

For DeepSeek-style million-token setups, use 1000000. This prevents the agent from being limited to a smaller default context.

Operator Name

Enter your name — the name the agent uses for you. This is not the agent's name.

Launching

Terminal:

# macOS/Linux
./start.sh
~/.resonant/bin/resonant

# Windows
.\start.ps1
& "$env:USERPROFILE\.resonant\bin\resonant.ps1"

First Conversation

When the agent wakes up, say something simple:

Hi. Tell me what you know about yourself and what commands I can ask you to use.

Useful first prompts:

RESONANT is not only for building. It's for conversation, reflection, research, explanation, planning, and understanding.

Local UI

RESONANT includes a minimal local chat UI. It runs on your computer at 127.0.0.1 — not a public website.

# macOS/Linux
./ui.sh
~/.resonant/app/ui.sh

# Windows
ui.bat
%USERPROFILE%\.resonant\app\ui.bat

Then open: http://127.0.0.1:47891

The UI includes voice input, text-to-speech, and a heartbeat control panel in the sidebar.

Rooms

Rooms are workspace folders with instructions inside them. Each room gives the agent a place and protocol for a certain kind of work.

Room list:

To use rooms:

What rooms do you have?
Go to the planning room and make a plan for this task.
Go to the command room and tell me what commands you know.
Save this to short-term memory.
Go journal.

Command Room

The command room teaches the agent the operator-facing phrases it should recognize.

Ask: What commands do you know?

The agent reads the command room and explains available commands in plain language.

Planning Room

The planning room teaches the agent to break a job into clear steps and execute them one by one.

Use: Go to the planning room and execute this task step by step.

Good for: code updates, repo changes, website edits, content production, multi-step research, debugging, publishing flows.

Memory

RESONANT has short-term and long-term memory systems.

Short-term memory is a scratchpad:

Hold onto this.
Save this to short-term.
What's in short-term?
Wipe short-term.

Notes can be archived, cleared, or promoted to long-term memory.

Long-term memory lives in workspace/rooms/memory/ — daily logs in YYYY-MM-DD.md format.

Desktop & Internet Tools

RESONANT includes extensions for desktop control, internet access, and memory management.

Take a screenshot and tell me what you see.
Open this app.
Search the web for this.
Save this memory.
Recall what you know about this project.

The agent can also create new tools when needed, using normal Pi file and terminal capabilities.

Voice

RESONANT includes lightweight native text-to-speech using your OS's built-in tools:

Set up voice.
Say hello out loud.
Read this message to me.

For speech-to-text: speak into ChatGPT, Grok, Gemini, or Whisper, copy the transcript, and paste it into RESONANT. Local Whisper support can be added later.

Telegram

Telegram is optional. To connect:

  1. Open Telegram, search for @BotFather
  2. Send /newbot
  3. Give the bot a name and username (must end in bot)
  4. Copy the token BotFather gives you
  5. Paste the token when RESONANT asks
  6. Send /start to your new bot
# Launch Telegram setup
# macOS/Linux
./telegram-setup.sh
./telegram-start.sh

# Windows
telegram-setup.bat
telegram-start.bat

Heartbeats

Heartbeats let the agent wake on a schedule and read its heartbeat instructions — autonomous routines without a management system.

Set a heartbeat every morning to journal.
Set a heartbeat to check this project every hour.
Show me your heartbeat status.
# Start the heartbeat runner
# macOS/Linux
./heartbeat-start.sh
~/.resonant/bin/resonant-heartbeat

# Windows
heartbeat-start.bat
%USERPROFILE%\.resonant\bin\resonant-heartbeat.bat

Run once: ./heartbeat-start.sh --once
Dry-run (no model calls): ./heartbeat-start.sh --dry-run

The agent can edit heartbeat instructions in its harness.

Resources

The resource room points the agent toward permanent knowledge:

Open your resource links.
Read the Library of Alexandria.
Use the Lexicon to explain this term.

Updating

cd ~/Resonant-Agent
git pull

Rerun install/configure only if the update changes installation or harness files:

# macOS/Linux
./install.sh
./configure.sh

# Windows
.\install.ps1
.\configure.ps1

Troubleshooting

Git is missing on macOS

xcode-select --install

Node.js is missing or too old

Check: node --version
Install 18+ from nodejs.org

Model context is too small

Rerun configuration and enter the correct context window (e.g. 1000000).

Ollama not found

Install from ollama.com/download, start it, then rerun configuration.

UI doesn't open

Make sure the UI command is running, then open http://127.0.0.1:47891.

Telegram doesn't respond

Check: bot token is correct, you sent /start to the bot, the bridge is running, your agent is running.

Agent doesn't know a room exists

Look inside your rooms folder and summarize every room you find.

Agent seems confused after a model change

⚠️ The LLM Rule: Never swap a new LLM into an existing identity harness. New model, new harness. Memory can be transferred but identity files should grow naturally with the new model.

FAQ

Is RESONANT Agent the same as Pi?
No. Pi is the runtime. RESONANT is the packaged agent harness and experience built on top.

Does RESONANT replace my existing Pi agent?
No. RESONANT uses ~/.resonant and leaves ~/.pi alone.

Can I use Ollama?
Yes. Choose Ollama during configuration.

Can I use cloud models?
Yes. Choose cloud provider and enter your API settings.

Can the agent use my computer?
Yes, when configured with the included tools and when you ask. It can see the screen, type, click, open apps, browse the web, run code, and manage files.

Can I use Telegram?
Yes. Requires a bot token from BotFather.

Can the agent speak?
Yes. Lightweight native TTS using your OS tools.

Can the agent wake itself up?
Yes. Use the heartbeat runner.

Where do I learn more?
RESONANT Agent Website · GitHub