Graph View

🐍 Ompycord Cheatsheet

🐍 OMPYCORD — Ultimate Over-Powered Cheat Sheet

Decoupled, robust, and emojified single source of truth for the OMP⇄Discord sidecar bridge.

1. ⚡ Speedrun Setup

🔧 Environment Config (/home/dv/.omp/plugins/ompycord/.env)

# 🔑 why: authenticate bot with Discord Gateway API
DISCORD_BOT_TOKEN=MTUxMTAx...
# 🌐 why: home channel where status reports and commands route
DISCORD_CHANNEL_ID=1514380270491402270
# 🏛️ why: restrict interactions to this specific server
DISCORD_GUILD_ID=1496176276933972110
# 👥 why: limit bot administrative actions to allowed user snowflakes
DISCORD_ALLOWED_USERS=481482311288750080,1148596028556197939
# 🚀 why: emoji trigger to launch new subagent process threads
OMP_LAUNCH_EMOJI=🚀
# 🎚️ why: channel IDs where reaction launches are active
OMP_LAUNCH_CHANNEL_IDS=1514380270491402270

🏃 Process Control

# 🚀 why: start the background daemon process
# 🛠️ what: spawns FastAPI on port 8901 and connects the Discord Gateway client
# ✂️ how: nohup keeps it running after ssh/terminal session closes
nohup /bin/bash /home/dv/.omp/plugins/ompycord/start.sh >/home/dv/.omp/plugins/ompycord/bot.log 2>&1 &
 
# 🛑 why: cleanly terminate bot daemon and uvicorn backend
# 🛠️ what: kills both the bash starter script and the python child process
# ✂️ how: pgrep searches command strings and pipes to SIGTERM
pgrep -f "python3 bot.py|start.sh" | xargs kill -9

2. 🎚️ Command Hub

👾 Hybrid Commands (/omp)

CommandTriggerTelemetry / Output
/omp statusManualRenders StatusSnapshot embed showing uptime, latencies, and checklist.
/omp healthDiagnosticsValidates STLink gateway ping and checks SQLite DB read/write connection.
/omp newSpawnCreates new thread session Session: <topic> under text channel.
/omp saysteeringQueues prompt into target thread, waking up the background subagent.
/omp cancelEmergencySends SIGTERM to the active OMP subprocess, stopping loops instantly.
/omp stopArchiveClears DB mapping, archives thread channel, and cleans system memory.
/omp queueTelemetryRenders depth of waiting prompts and list of next tasks.
/omp versionTelemetryOutputs process ID (PID), code build versions, and daemon uptime.

3. 💾 DB Architecture

db.py handles database migrations and queries. bot.py is fully decoupled from SQL syntax.

# 📂 path: /home/dv/.omp/plugins/ompycord/db.py
import aiosqlite
 
DB_PATH = "/home/dv/.omp/plugins/ompycord/sessions.db"
 
# 🗑️ why: delete mapped thread session from SQLite database upon stop/archive command
# 🛠️ what: removes row matching thread ID from active sessions table
# ✂️ how: db.execute("DELETE FROM agent_sessions WHERE discord_thread_id = ?", (thread_id,))
async def delete_session_by_thread(thread_id: int) -> None:
    async with aiosqlite.connect(DB_PATH) as db:
        await db.execute("DELETE FROM agent_sessions WHERE discord_thread_id = ?", (thread_id,))
        await db.commit()
 
# 🔍 why: retrieve active dashboard message ID to edit or relocate panel
# 🛠️ what: selects dashboard_message_id matching session key
# ✂️ how: returns row[0] if it exists, else None
async def get_dashboard_message_id(session_id: str) -> Optional[int]:
    async with aiosqlite.connect(DB_PATH) as db:
        async with db.execute(
            "SELECT dashboard_message_id FROM agent_sessions WHERE session_id = ?",
            (session_id,)
        ) as cursor:
            row = await cursor.fetchone()
            return row[0] if row else None

4. 🚀 Launch Pipeline

Triggers automatic thread creation and agent bootstrapping from reaction clicks.

sequenceDiagram
    participant User as 👥 User
    participant Gateway as 📡 Discord Gateway
    participant Daemon as 🐍 Ompycord bot.py
    participant DB as 💾 db.py
    participant Subprocess as ⚙️ Subprocess

    User->>Gateway: Reacts 🚀 to Message
    Gateway->>Daemon: on_raw_reaction_add()
    Daemon->>Daemon: Debounce check (active_launches)
    Daemon->>Gateway: create_thread() & fetch_message()
    Daemon->>DB: register_session(session_id, thread_id)
    Daemon->>Subprocess: run_omp_subprocess()
    Note over Daemon,Subprocess: Stream logs & update embeds
    Subprocess->>Daemon: Exit process (done / fail)
    Daemon->>Daemon: Discard message ID from active_launches

🔒 Debounced Launcher Hook

# 📂 path: /home/dv/.omp/plugins/ompycord/bot.py
 
@bot.event
async def on_raw_reaction_add(payload: discord.RawReactionActionEvent):
    # 🚫 why: prevent bot from triggering its own message reactions
    if payload.user_id == bot.user.id: return
    # 🚀 why: filter out any emoji other than the designated launch rocket
    if str(payload.emoji) != os.getenv("OMP_LAUNCH_EMOJI", "🚀"): return
    # 🔒 why: avoid double-click concurrent thread spawn bugs
    if payload.message_id in active_launches: return
    active_launches.add(payload.message_id)
 
    try:
        # 📂 why: extract text content and spawn thread channel
        channel = bot.get_channel(payload.channel_id) or await bot.fetch_channel(payload.channel_id)
        message = await channel.fetch_message(payload.message_id)
 
        # 👤 why: security guard, verify reaction clicker matches message author
        if message.author.id != payload.user_id:
            active_launches.remove(payload.message_id)
            return
 
        thread = await message.create_thread(name=f"Run: {message.content[:20]}")
        session_id = f"session_{uuid.uuid4().hex[:8]}"
        await register_session(session_id, thread.id)
 
        # ⚙️ why: run agent command process asynchronously
        asyncio.create_task(run_omp_subprocess(session_id, message.content, thread, message.id))
    except Exception:
        active_launches.discard(payload.message_id)
        raise

5. ⚙️ Subprocess Loop

# 📂 path: /home/dv/.omp/plugins/ompycord/bot.py
 
async def run_omp_subprocess(session_id: str, prompt: str, thread: discord.Thread, message_id: Optional[int] = None):
    # ... setup command ...
    try:
        process = await asyncio.create_subprocess_exec(*cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
 
        while True:
            line = await process.stdout.readline()
            if not line: break
 
            # 🔍 why: prevents UnicodeDecodeError from crashing the loop if binary/malformed bytes are output
            # 🛠️ what: decodes stream bytes to string, ignoring decoding issues
            # ✂️ how: line.decode("utf-8", errors="ignore")
            log_line = line.decode("utf-8", errors="ignore").strip()
            if log_line:
                log_buffer.append(log_line)
                if len(log_buffer) >= 10 or (time.time() - last_flush_time >= 1.5):
                    await flush_logs()
        await flush_logs()
        await process.wait()
    finally:
        # 🔒 why: guarantee release of launch lock even if subprocess fails
        if message_id is not None:
            active_launches.discard(message_id)
        # ... unpin prompt & repaint dashboard state ...

6. 🎨 Dashboard States

Interactive dashboards visualize live agent metrics through colors.

StatusColorEmojiDescription
Idle0x2ECC71🟢Daemon is online, ready for prompt inputs.
Busy0x5865F2🔵Subprocess execution loop is active.
Waiting0xF1C40F🟡Interactive modal/select is awaiting user click.
Degraded0xE67E22🟠Subprocess returned warnings or execution failed.
Failed0xE74C3C🔴Core daemon process is unresponsive or offline.

7. 🔌 Sidecar API

The sidecar daemon runs an asynchronous FastAPI router exposing endpoint handlers on port 8901:

# 📢 why: receive real-time execution step telemetry from the active OMP agent
POST http://127.0.0.1:8901/api/webhook/event
Content-Type: application/json
{
  "session_id": "session_a4b91f0",
  "event_type": "tool_call",
  "content": "Running search...",
  "timestamp": "2026-06-13T22:00:00Z"
}
 
# 📥 why: allow OMP agent to poll for queued steering commands from thread
GET http://127.0.0.1:8901/api/commands/poll?session_id=session_a4b91f0

8. 🗺️ Canvas Alignment

📏 Grid Alignment Rules

  • Height: File nodes must have a standard height of 80px.
  • Gap: Space nodes vertically by a strict 20px gap (100px coordinate spacing).
  • Group Height: Automatically adjust group wrapping boundaries to prevent overlaps.

🗺️ specs.canvas Coordinates Matrix

Node IDTarget FileXYWidthHeightColor
f-cs2docsskills/cs2docs.md40100480806
f-docskurbyskills/docskurby.md40200480806
f-llmwikiskills/llm-wiki.md40300480806
f-skillsskills/SKILLS.md40400480806
f-skills-cheatskills/SKILLS-CHEATSHEET.md40500480806
f-ompstack/omp.md1760100480804
f-ompkeepstack/ompkeep.md1760200480804
f-quartz5stack/quartz5.md1760300480804
f-planningplans/planning-standard.md40920480803
f-migrationplans/w-0rk-migration/index.md401020480803
f-ompycordprojects/ompcord/ompycord.md920720480803
f-reviewprojects/ompcord/ompycord-review.md920820480803
f-unidialogprojects/ompcord/unidialog.md920920480803
f-ssotembedprojects/ompcord/ssotembed.md9201020480803
f-redvsompprojects/ompcord/red-vs-omp.md9201120480803
f-cheatsheetprojects/ompcord/cheatsheet.md9201220480803
f-llmstxtknowledge/cognitive-fs/llms-txt.md1760720480802
f-projectsknowledge/cheatsheets/projects.md1760820480802
f-smokmodknowledge/cheatsheets/novo-modding/index.md1760920480802
f-biblebible.md17601020480802
Properties3
descriptionHigh-density quick-start reference and cheatsheet for the Ompycord Discord bridge daemon
tagscheatsheet, discord, python, ompycord
aliasescheatsheet