✨ What Ares is

Ares is a terminal-first AI assistant with a separate Next.js power workspace, an optional local WebSocket API, voice interface, Android phone bridge, and allowlisted Telegram channel. It combines an OpenAI-compatible model client with a local SQLite data layer, an append-only session archive, reusable skills, and a broad local tool surface.

Latest upgrades

• Goal-aware monitoring: link one watcher to multiple goals, review routed signals in both watcher consoles, and keep progress changes explicit instead of automatic.
• Research delivery: search and rank web sources, fetch online pages/PDFs/reports, extract readable content, save sourced artifacts, and deliver supported files through Telegram.
• Power workspace: isolated background chats, smooth token streaming, cached history with skeleton loading, structured tool traces, and built-in previews for Markdown, PDFs, images, and generated files.
• One runtime: python -m ares --all starts chat, Telegram, integrations, watchers, the workspace, and the advanced console around the same Ares agent.

🚀 Quick start

Terminal

git clone https://github.com/akyourowngames/friday.git
cd friday
pip install -e ".[dev]"
python -m ares

Voice mode

pip install -e ".[voice]"
python -m ares --voice

Unified always-on runtime

python -m ares --all
# Desktop API: ws://127.0.0.1:8765
# Power workspace: http://127.0.0.1:8766
# Advanced watcher console: http://127.0.0.1:8080

--all owns one agent, one integration manager, one watcher scheduler, the Next.js power workspace, the advanced watcher console, the desktop API, and Telegram when it is enabled. --server remains a compatibility alias; watchers are tools used by Ares and are not launched as an independent product process.

Next.js power workspace

The power workspace is intentionally separate from the public marketing website. It provides one operational surface for streaming Ares chat, reusable file uploads, skills, MCP connections, watcher fleet management, personalization, browser configuration, Telegram setup, and advanced runtime settings. Chat, watcher actions, MCP operations, and settings all use the same running Ares agent and WebSocket protocol.

The production build is bundled with the Python package and served at http://127.0.0.1:8766 by python -m ares --all. For frontend development:

cd ares-workspace
npm install
npm run dev

npm run build creates the static Next.js export and synchronizes it into ares/workspace/static for the Python runtime.

[!TIP]
Start in the terminal first. Use /setup, /model, /context, and /help to inspect the active configuration and available controls.

📡 Proactive watchers

Ares can run a durable monitoring fleet over websites, REST/JSON APIs, numeric thresholds, permitted Instagram Graph API endpoints, authenticated Playwright pages, and the results of existing Ares or connected MCP tools. Watchers are part of the normal agent tool plane: you can ask Ares to create, inspect, run, pause, resume, or query them in natural language.

The control plane is local by default and includes:

• A real-time overview, fleet health, incident queue, latency telemetry, delivery-channel health, and persistent settings.
• SHA-256, text diff, and numeric threshold detection with regex noise suppression and first-run baselines.
• Concurrent scheduling, cross-process leases, bounded fetch timeouts, exponential retry backoff, auto-pause after repeated failures, and snapshot retention.
• Telegram, desktop, email, and webhook delivery with per-channel attempt logs and background retries.
• Optional Ares analysis for suggestions and explicit, auditable webhook-only automatic actions.
• SSRF protection, private-network opt-in, cross-origin redirect controls, secret redaction, and optional ARES_WATCHER_API_TOKEN dashboard authentication.
• Bounded read-only tool workflows that reuse phone, files, web, browser, and MCP integrations. Consequential steps such as clicks, typing, sending, deletion, or shell execution require global and per-watcher opt-in.

Examples you can ask Ares directly:

Monitor my Instagram DMs every 5 minutes using my authenticated Playwright session.
Watch my Android notifications and alert me when a new banking notification appears.
Create a watcher over the GitHub MCP tool result for open production incidents.
Show failing watchers and acknowledge the incident from the deployment-status watcher.
Run the Instagram inbox watcher now and tell me what changed.

The agent exposes create_watcher, list_watchers, get_watcher, update_watcher, run_watcher_now, fleet/event query tools, pause/resume, acknowledgement, capability discovery, and confirmed deletion. Use get_watcher_capabilities when Ares needs to inspect the currently connected MCP tools before building a workflow.

Goal-aware watcher signals

Watchers can be linked to one or many durable goals. Pass goal_id to create_watcher for a one-step setup, or use link_goal_watcher later. Every detected change is fanned out idempotently using the watcher event UUID and stored in goal_watcher_signals with severity, old/new values, source provenance, snooze state, resolution, and surface count.

A signal never changes goal progress or status. It appears in goal context for at most three turns during its first 48 hours, then remains available through get_goal_signals or /goals signals without nagging. The user can snooze or dismiss it, or explicitly confirm an update_goal/complete_goal call with resolves_signal_id; that mutation and signal acknowledgement share one SQLite transaction. Once every goal-specific copy is resolved, Ares reconciles the originating watcher incident too.

See docs/goal-watcher-integration.md for the runtime sequence, persistence contract, anti-nag rules, and operator examples.

Create a goal to buy a laptop under $1,000, then watch this product page and link it.
Show pending watcher signals for my laptop goal.
Not now—snooze signal 12 for two days.
Yes, the price is low enough; complete the goal and resolve signal 12.

For authenticated DMs, configure /browser extension or /browser system, sign in normally, and let the browser watcher navigate to or snapshot the inbox. Ares stores the captured signal—not your password—and never automates credential entry. The dashboard’s Browser / DMs (Playwright) source includes an Instagram inbox starter recipe; Ares tool workflow provides a visible JSON workflow editor for any read-only tool chain.

Terminal controls use short IDs or exact names:

/monitor add "Production status" https://status.example.com --interval 5m --type website
/monitor add "Laptop price" https://shop.example.com/laptop --interval 15m --goal 12
/monitor list
/monitor status ID
/monitor pause ID
/monitor resume ID
/monitor events ID
/monitor test ID
/monitor remove ID

Telegram exposes /monitors, /monitor ..., and /alerts. The scheduler starts automatically in Ares when watcher.enabled is true. Use python -m ares --all for the unified always-on runtime; database leases remain as a defensive guarantee against duplicate checks during upgrades or accidental overlapping processes.

Watcher configuration is stored under the shared watcher object in ~/.ares/config.json. Notification passwords and bot tokens can remain outside the file through ARES_WATCHER_SMTP_PASSWORD and ARES_TELEGRAM_BOT_TOKEN.

{
  "watcher": {
    "enabled": true,
    "tool_monitors_enabled": true,
    "allow_mutating_tool_steps": false,
    "max_tool_steps": 8,
    "dashboard": { "enabled": true, "host": "127.0.0.1", "port": 8080 }
  }
}

Keep allow_mutating_tool_steps off for normal monitoring. Enabling a consequential workflow also requires "allow_mutating_tools": true on that specific watcher, and should only be used for an explicitly reviewed automation. Respect the monitored service’s permissions and terms.

🧭 How it fits together

flowchart LR
    User([You]) --> CLI[Rich terminal]
    User --> Voice[Voice mode]
    User --> Telegram[Telegram channel]

    CLI --> Agent[Ares agent]
    Voice --> Agent
    Telegram --> Agent

    Agent --> Context[Context blend]
    Agent --> Tools[Tool executor]
    Agent --> LLM[OpenAI-compatible LLM]

    Context --> Data[(Local Ares data)]
    Data --> Facts[Memory + people + conversations]
    Data --> Sessions[Append-only JSONL sessions]
    Data --> Tasks[Tasks + actions + cron]

    Tools --> Local[Files · shell · code · images]
    Tools --> Bridges[Phone · web · MCP servers]

🧠 Memory that can explain itself

The current recall system is deliberately broader than a single “memory facts” table. A question can search all local evidence sources at once:

search_memory reads session JSONL files directly on every lookup rather than depending on a stale side index. It also searches a small neighboring-turn window. That means a question such as “What was Rohit’s Instagram ID?” can recover a name in one historical turn and the ID in the next, then return the exact local source ID that produced the answer.

Session line 17  User:      Rohit Verma is my cousin.
Session line 18  Assistant: His Instagram ID is @rohit_dev_42.

search_memory("Rohit Instagram")
  → session:sess-a1b2:line:18
  → @rohit_dev_42

[!NOTE]
Local history is evidence, not live external state. Ares preserves what was saved and identifies where it came from; it does not invent a detail that was never written to disk.

Continuity upgrades

• Full local recall: facts, people, conversations, sessions, and actions in one tool result.
• Session resilience: malformed historical JSONL lines are skipped without discarding the rest of a session.
• Context continuity: “continue,” “that session,” and person references can pull relevant archived turns into context.
• Structured people: names, aliases, relationship notes, contact fields, and important dates are stored and retrieved as one local record.
• Evidence-backed goals: multi-level outcomes, due dates, priorities, manual/derived progress, task/action/watcher links, proactive signal review, and an append-only check-in timeline live in the shared database.
• Durable workflows: task plans, leases, retries, verification steps, and a confirmation-aware runner survive process restarts.
• Action provenance: file, communication, export, and workflow outcomes can be located later without storing arbitrary command bodies.

🛠️ Capability map

Local tool groups

See the complete model-facing inventory in ares/tools/definitions.py.

🧩 Built-in skills

Skills are local SKILL.md playbooks. Ares discovers relevant instructions, loads them silently when appropriate, and keeps them reusable across surfaces.

Skill discovery order:

~/.ares/skills  →  .ares/skills  →  .agents/skills  →  ares/skills

Useful commands:

/skills
/skills search code review
/skills info memory-consolidator
/skills create release-checklist
/skills load browser-use

🔌 MCP integrations

Ares exposes connected MCP tools to the agent as mcp__server__tool. The bundled configuration includes these local integration templates:

Manage connections without editing code:

/mcp status
/mcp tools playwright
/mcp health
/mcp reconnect windows
/mcp search browser automation
/mcp add SERVER

See MCP configuration and diagnostics for stdio, SSE, and Streamable HTTP server examples, browser modes, and OAuth token storage.

💬 Voice, phone, and Telegram

Provider-backed phone calls

Install the optional runtime, then enable Telephony in desktop Settings. Ares provides both local processes: a signed Twilio callback server and a bidirectional Media Streams gateway. Publish their loopback ports through HTTPS/WSS (for example with a reverse proxy or tunnel), then save the public addresses in telephony.public_base_url and telephony.media_stream_url. A Twilio-owned E.164 caller number is also required.

pip install -e ".[telephony]"

# Start these in separate terminals. They bind only to the local machine.
python -m ares --telephony-webhook --telephony-webhook-port 8080
python -m ares --telephony-media-gateway --telephony-media-port 8767

The media gateway converts Twilio's 8 kHz mu-law stream to local Whisper input, runs the normal Ares agent (including memory and tools), and returns Edge TTS audio to the call. It does not select an OpenAI realtime model. LiveKit project credentials are accepted and verified by locally signing a room token; audio routing to a separate LiveKit room remains an optional deployment integration rather than an implicit external dependency.

Ares stores call sessions, transcripts, summaries, and encrypted telephony contacts locally in ~/.ares/data/ares.db; the encryption key lives separately at ~/.ares/data/telephony.key.

/call Mom
/call +911234567890 --confirm
/telephony status
/contacts
/recent-calls
/hangup CALL_ID

Run /telephony status to see redacted readiness. It reports missing deployment fields without displaying credentials. No call is placed until you explicitly use /call.

Telegram setup

# Create a BotFather bot first, then configure its token locally.
python -m ares --telegram-setup

# After your bot replies with its chat ID, authorize that exact chat on the PC.
python -m ares --telegram-authorize 123456789

Telegram uses long polling: no public IP, webhook, or port forwarding is required. Authorized chats can use /new, /status, /skills, /mcp, and /file; unknown chats never receive tool access.

⌨️ Everyday commands

🗂️ Local data layout

~/.ares/
├── config.json                 # Model, bridges, MCP, and surface configuration
├── data/
│   ├── ares.db                 # Facts, people, goals, goal-watcher signals, conversations, actions, cron
│   ├── watchers.db             # Watchers, snapshots, incidents, checks, and notification attempts
│   ├── telephony.key           # Local Fernet key for encrypted call-contact numbers
│   ├── sessions/*.jsonl        # Append-only session archive with line provenance
│   ├── soul.md                 # Assistant personality
│   ├── profile.md              # User profile
│   ├── mcp_tokens/             # OAuth tokens for MCP servers
│   └── channels/telegram/inbox # Files received for related Telegram turns
└── skills/                     # User-installed local skills

🧪 Development and verification

# Python behavior
python -m pytest -q

# Next.js power workspace
cd ares-workspace
npm run lint
npm run typecheck
npm run build

🔐 Local-first boundaries

• Ares stores its local state under ~/.ares by default.
• Web search sends queries to the selected provider; connected MCP servers run according to your local configuration.
• Phone controls operate through your paired Android device.
• Real-world and destructive actions remain explicit in their relevant tool workflows.
• Do not commit API keys, OAuth tokens, or secrets. Exported configuration redacts recognized secret fields.

📚 Further reading

• MCP configuration and management
• Marketplace guide
• Watcher service design
• Watcher core implementation plan
• Contributing guide
• Code of conduct
• Changelog

License

MIT