Syll

<em>a small, self-hosted AI companion


who sits at the edge of your screen and quietly tends


the things you almost forgot</em>







<img src="https://img.shields.io/badge/version-0.2.0-blue" alt="Version">
<img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: alpha">
<img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">







<strong>Syll is a self-hosted companion runtime with a web UI, chat channels, proactive rituals, editable markdown skills, recorded workflows, and a desktop ghost.</strong>







<a href="https://thu-sage.github.io/syll/"><strong>Project page →</strong></a>
&nbsp;·&nbsp;
<a href="#quick-start">Quick start</a>
&nbsp;·&nbsp;
<a href="#demo-workbench">Demos</a>
&nbsp;·&nbsp;
<a href="https://github.com/THU-SAGE/syll/raw/v0.2.0/docs/lore.md">The Full Story · 故事</a>
&nbsp;·&nbsp;
<a href="https://thu-sage.github.io/syll/research.html">Research</a>
&nbsp;·&nbsp;
<a href="https://github.com/THU-SAGE/syll/raw/v0.2.0/docs/report/syll-report-v1.pdf">Paper</a>

---

Feature news

• MCP servers are now first-class tools. Configure stdio, SSE, and streamable-HTTP MCP servers from the Pet UI; Syll loads them into the agent as namespaced mcp__server__tool tools before the first message.
• Safer MCP activation flow. Local stdio servers require a command preview + hash confirmation before anything launches, while env/header secrets stay masked in MCP responses and out of /api/v1/config.
• Creative MCP templates included. The public build ships Playwright, Stagehand, Blender, and Godot template suggestions; Blender uses uvx blender-mcp, and Godot pins GoPeak MCP for reproducible local game-scene automation.
• Static asset refresh polish. The web app now cache-busts bundled JS/CSS assets so UI changes reach the browser without stale app.js surprises after the next restart.

---

Quick start

Syll works with any Python 3.11+ environment. Pick either main path, then run the shared install steps.

Option A — conda

conda create -n syll python=3.11 -y
conda activate syll

Option B — venv

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

Install and wake

python -m pip install -U pip
python -m pip install syll

syll onboard
syll wake

Open http://localhost:18790, click the Pet tab, give your ghost a name (or keep Syll), and start a conversation.

[!NOTE] The package, CLI, and import path are all syll. Syll is the default persona inside the companion you just installed; rename her to anything via the Pet tab at any time without touching code.

uv fast path

uv venv
source .venv/bin/activate
uv pip install syll
syll onboard
syll wake

Configure a model

Set your LLM credentials in ~/.syll/config.json, or finish setup from the web UI after syll wake:

{
  "models": {
    "chat": {
      "model": "openrouter/openai/gpt-4o-mini",
      "api_key": "YOUR_API_KEY"
    }
  }
}

Get keys: OpenRouter · OpenAI · Anthropic. Local models via vLLM / Ollama are also supported — see docs/references/local-models.md.

Troubleshooting

• syll onboard says "Config already exists" — answer N unless you intentionally want to replace your current ~/.syll/config.json and workspace.
• syll runs from the wrong environment — prefer python -m pip install syll, then check which python, python -m pip -V, and which syll point at the same environment.
• SYLL__* env vars are not picked up — use the SYLL__SECTION__FIELD=value shape, export the variable in your shell, and restart Syll.

---

Visual tour

Click any card to watch the short MP4.

1. Configuration Set models, channels, identity, and runtime options from the browser.	2. GUI calibration Inspect screenshots, calibrate coordinates, and make desktop actions reproducible.
3. Skill editor Edit markdown skills in the web UI and publish reusable procedures.	4. Leading mode Let Syll guide an interactive task while the desktop ghost stays present.
5. Scheduling Install rituals or schedule your own recurring jobs and workflow replays.	6. Web chat Chat locally from the browser while watching runtime state and logs.
7. Persona & memory Shape the companion persona and maintain layered memory notes.	8. Demo recording Capture a live desktop routine into video and editable step traces.

---

What Syll can do

She finds files you can't find. Ask her from your phone to grab the weekly report from your desktop. She walks your filesystem, renders thumbnails, shows you the candidates, and hands you the one you pick.

She keeps soft watch over unfinished things. The draft you open and close without writing anything. The photo folder from three years ago. She notices. She doesn't nag.

She reaches out sometimes. Morning light, evening winding down, a Tuesday afternoon when a memory drifts back. Not every time. Only when it would feel real. You control the cadence.

She can live on your phone instead of your desk. Pair her with Feishu, Telegram, Discord, or WhatsApp and she'll come with you.

She teaches herself new tricks. Give her a markdown skill (SKILL.md) and she loads it when the moment calls for it. Capture a GUI workflow once in the Demo tab, clean it up, and she can replay or schedule it later.

She comes with a visual workbench, not just a terminal. Models, channels, schedule rules, identity, skills, and recorded workflows all have a browser surface now — so ordinary users can configure her without living in a CLI.

She remembers in layers. The Memory tab surfaces long-term notes, today's journal, daily fragments, and an activity heatmap so her recollection feels like a notebook instead of a raw log dump.

She can stay at the edge of your desktop. The optional desktop ghost mirrors her state, reacts to wake/sleep transitions, and gives the companion a physical place to live between chats.

---

Meet her three ways

If you want…	Go here
For a softer intro	The project page →
To read the code or contribute	This repo (syll/ directory)
To cite the design or understand the architecture	The research page →

---

Channels

Channel	Status	Setup difficulty
Web UI	✓	none — just syll wake
CLI	✓	none — syll agent -m "hi"
Telegram	✓	easy — one bot token
Feishu	✓	medium — app_id + app_secret, supports file send
Discord	✓	easy — bot token + intents
WhatsApp	✓	medium — QR scan (text only)

Telegram setup

1. Open Telegram, search @BotFather, send /newbot, follow prompts, copy the token.
2. Configure ~/.syll/config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

1. Run syll wake.

Feishu setup

1. Create an app at open.feishu.cn, enable bot capability, enable long-connection websocket event subscription, and grant im:message, im:message.p2p_msg, and im:resource permissions.
2. Configure ~/.syll/config.json:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxx",
      "app_secret": "xxx"
    }
  }
}

1. Run syll wake. No public IP needed — WebSocket long-connection handles inbound events.

Discord / WhatsApp setup

See docs/references/channels.md for full setup steps.

---

Proactive rituals

Let Syll reach out to you on her own schedule. Pet tab → set a Chat ID for your primary channel → Save → click Install default rituals. Four jobs land in the scheduler:

• ritual:morning-light — 9am daily, one soft greeting
• ritual:evening-wind-down — 10pm daily, a small closing thought
• ritual:surfacing-memory — Tue/Fri 3pm, maybe a drifting memory
• ritual:week-close — Sunday 9pm, a week marker

Silence is always a valid response. She only speaks when it would feel real.

Full details: syll/templates/workspace/lore/rituals.md.

The same scheduler can also run GUI skills and recorded workflows from the web UI — useful for recurring check-ins, daily collection jobs, or replaying a polished browser routine on a timer.

---

Skills

Skills are markdown files that teach Syll how to do a specific thing. Built-in skills live in syll/skills/; custom skills go in ~/.syll/workspace/skills/{name}/SKILL.md.

A skill can be:

• Progressive — listed in the prompt summary, loaded when needed
• Always-on — marked always: true in metadata, inlined into every system prompt

Bundled skills: file-retrieval (find → preview → attach), github, weather, tmux, cron, summarize, skill-creator, gui-agent.

Write your own: syll/skills/skill-creator/SKILL.md.

Recorded workflows are the sister surface to markdown skills: capture a task once, inspect the video + trajectory, edit coordinates / timestamps / notes in the Demo tab, then publish it into the reusable library for replay or scheduling.

---

Demo workbench

Open the Demo tab to move from one-off capture to reusable automation:

• capture a live desktop session into video + step trajectory
• scrub the recording on a timeline and preview exact keyframes
• merge, duplicate, delete, or relabel steps before publishing
• import the cleaned flow as a reusable recorded workflow
• schedule the same workflow later from the Schedule tab

This is the layer that turns a personal "watch me do it once" demo into something Syll can execute again on demand.

Append ?cinema to the project page URL for recording-friendly playback.

Demo videos

The public demo set lives under docs/media/demo/, so the same web-ready files back both GitHub Pages and the README.

• Recorded workflow studio — capture a desktop routine, inspect the timeline, clean the step trace, and publish it as a reusable workflow. Research note · Watch MP4
• Morning ritual briefing — a scheduled ritual wakes up, gathers context, and delivers a voice-ready daily update. Research note · Watch MP4
• Phone-to-desktop file return — ask from chat for a presentation, confirm the match, and receive the file back without going back to the desktop. [Research note](https://thu-sage.github.io/syll/research.htm