Osori (오소리)

Local project registry & context loader for AI agents.

Prerequisites

• macOS: mdfind (Spotlight, built-in), python3, git, gh CLI
• Linux: mdfind unavailable → uses find as fallback automatically. python3, git, gh CLI required.
• Entire integration (optional): entire CLI installed (for /entire-* commands)

Dependencies

• python3 — Required. Used for JSON processing.
• git — Project detection and status checks.
• entire — Optional. Required only for /entire-status, /entire-enable, /entire-rewind-list.

Telegram Bot Commands (Updated in v1.6.1)

Osori now supports Telegram slash commands for quick project management:

/list [root] — Show registered projects (optional root filter)
/status [root] — Check status of projects (optional root filter)
/find <name> [root|--root <root>] — Find a project by name (optional root scope)
/switch <name> [root|--root <root>] [--index <n>] — Switch to project and load context (multi-match selection)
/fingerprints [name] [--root <root>] — Show repo remote + last commit + open PR/issue counts
/doctor [--fix] [--dry-run] [--yes] [--json] — Registry health check (preview-first, risk-gated)
/list-roots — List roots, labels, paths, and project counts
/root-add <key> [label] — Add root (or update label)
/root-path-add <key> <path> — Add discovery path to root
/root-path-remove <key> <path> — Remove discovery path from root
/root-set-label <key> <label> — Update root label
/root-remove <key> [--reassign <target>] [--force] — Safely remove root
/alias-add <alias> <project> — Add alias for project
/alias-remove <alias> — Remove alias
/favorites — Show favorite projects
/favorite-add <project> — Mark project as favorite
/favorite-remove <project> — Unmark favorite
/entire-status <project> [root|--root <root>] — Show Entire status in a project
/entire-enable <project> [root|--root <root>] [--agent <name>] [--strategy <name>] — Enable Entire in a project
/entire-rewind-list <project> [root|--root <root>] — List rewind points in a project
/add <path> — Add project to registry
/remove <name> — Remove project from registry
/scan <path> [root] — Scan directory for git projects, optional root key
/help — Show command help

Setup

Add to your OpenClaw agent's TOOLS.md or Telegram bot config:

# In Telegram bot commands (BotFather)
list - Show all projects (or by root)
status - Check project statuses (or by root)
find - Find project by name
switch - Switch to project
fingerprints - Show repo/commit/PR/issue fingerprint
doctor - Health check (preview-first, risk-gated fix)
list-roots - Show roots and discovery paths
root-add - Add root
root-path-add - Add path to root
root-path-remove - Remove path from root
root-set-label - Rename root label
root-remove - Safely remove root (with reassign/force options)
alias-add - Add alias for a project
alias-remove - Remove alias
favorites - Show favorite projects
favorite-add - Mark favorite project
favorite-remove - Unmark favorite project
entire-status - Show Entire status for a project
entire-enable - Enable Entire for a project
entire-rewind-list - List rewind points for a project
add - Add project to registry
remove - Remove project
scan - Scan directory (optional root)
help - Show help

Usage Examples

/list work
/status personal
/find agent-avengers work
/switch Tesella --root personal
/switch Tesella --root personal --index 1
/fingerprints Tesella --root personal
/doctor --fix
/list-roots
/root-add work Work
/root-path-add work /path/to/workspace
/root-remove work --reassign default
/alias-add rh RunnersHeart
/favorite-add RunnersHeart
/favorites
/entire-status osori
/entire-enable osori --agent claude-code --strategy manual-commit
/add /Volumes/disk/MyProject
/scan /path/to/workspace work

Registry

${OSORI_REGISTRY:-$HOME/.openclaw/osori.json}

Override with the OSORI_REGISTRY environment variable.

Versioning & Migration (v1.6.1)

• Current schema: osori.registry
• Current version: 2
• On every load, Osori auto-migrates older registry formats:
• legacy array ([]) → versioned object
• object without schema/version → normalized versioned object
• Normalized registry fields:
• top-level roots[]
• top-level aliases{} (alias → project name)
• each projects[] item includes favorite: bool
• Migration safety:
• creates backup: osori.json.bak-
• corrupted JSON is preserved as: osori.json.broken-
• write path uses atomic replace + rollback fallback

Finding Projects (when path is unknown)

When the project path is unknown, search in order:

1. Registry lookup — Fuzzy match name in osori.json
2. mdfind (macOS only) — mdfind "kMDItemFSName == ''" | head -5
3. find fallback — Search priority:

1) roots[].paths from registry (if root is specified, that root first)

2) paths from OSORI_SEARCH_PATHS

Command form: find -maxdepth 4 -type d -name '' 2>/dev/null

1. Ask the user — If all methods fail, ask for the project path directly.
2. Offer to register the found project in the registry.

Commands

List

Show all registered projects. Optional root filter supported in Telegram command:

/list [root]

(Example: /list work)

Switch

Supports optional root scope and explicit candidate selection:

/switch <name> [root|--root <root>] [--index <n>]

Flow:

1. Search registry (fuzzy match, root-scoped if provided)
2. If multiple matches:
• show candidate list (name/root/path/last commit/dirty/score)
• --index to pick explicitly
• no index => auto-pick highest score
3. If not found → run "Finding Projects" flow above and suggest add path
4. Load context:
• git status --short
• git branch --show-current
• git log --oneline -5
• gh issue list -R --limit 5 (when repo is set)
5. Present summary

Auto score policy:

• +50 root exact (if root scope provided)
• +30 name exact
• +20 name prefix
• +10 latest commit recency
• -10 missing path
• -5 repo missing
• tie-break: latest commit, then name

Fingerprints

Show a one-shot project fingerprint view:

• repo remote URL
• last commit hash/date
• open PR count
• open issue count

bash {baseDir}/scripts/project-fingerprints.sh [project-name]
bash {baseDir}/scripts/project-fingerprints.sh --root <root-key> [project-name]

GitHub open-count cache (PR/Issue):

• default cache file: $HOME/.openclaw/osori-cache.json
• default TTL: 600 seconds
• env overrides:
• OSORI_CACHE_FILE
• OSORI_CACHE_TTL

Add

bash {baseDir}/scripts/add-project.sh <path> [--tag <tag>] [--name <name>]

Auto-detects: git remote, language, description.

Scan

bash {baseDir}/scripts/scan-projects.sh <root-dir> [--depth 3]
OSORI_ROOT_KEY=work bash {baseDir}/scripts/scan-projects.sh <root-dir> [--depth 3]

Bulk-scan a directory for git repos and add them to the registry.

Telegram command supports optional root key too:

/scan <path> [root]

Remove

Delete an entry from osori.json by name.

Status

Run git status + gh issue list for one or all projects.

Telegram root filter:

/status [root]

Doctor

Registry health check with preview-first pipeline and risk-gated fixes.

Default (no flags): analyze + preview plan — no changes applied.

/doctor                     # preview only (default)
/doctor --fix               # preview + apply (high-risk blocked)
/doctor --fix --yes         # preview + apply all (including high-risk)
/doctor --dry-run           # explicit preview only (never applies)
/doctor --json              # machine-readable JSON output

Risk levels:

• 🟢 low — schema normalization, migration, missing fields
• 🟡 medium — duplicate removal, root reference repair
• 🔴 high — registry re-initialization from corrupted state

Shell equivalent:

bash {baseDir}/scripts/doctor.sh [--fix] [--dry-run] [--yes] [--json]

See also: Doctor Safe Fix Guide

Root Management

/list-roots
/root-add <key> [label]
/root-path-add <key> <path>
/root-path-remove <key> <path>
/root-set-label <key> <label>
/root-remove <key> [--reassign <target>] [--force]

Shell equivalents:

bash {baseDir}/scripts/root-manager.sh list
bash {baseDir}/scripts/root-manager.sh add <key> [label]
bash {baseDir}/scripts/root-manager.sh path-add <key> <path>
bash {baseDir}/scripts/root-manager.sh path-remove <key> <path>
bash {baseDir}/scripts/root-manager.sh set-label <key> <label>
bash {baseDir}/scripts/root-manager.sh remove <key> [--reassign <target>] [--force]

Safety rules for remove:

• default root cannot be removed
• if projects exist in root:
• --reassign to move projects then remove
• or --force to move projects to default and remove

Alias & Favorites

/alias-add <alias> <project>
/alias-remove <alias>
/favorites
/favorite-add <project>
/favorite-remove <project>

Shell equivalents:

bash {baseDir}/scripts/alias-favorite-manager.sh alias-add <alias> <project>
bash {baseDir}/scripts/alias-favorite-manager.sh alias-remove <alias>
bash {baseDir}/scripts/alias-favorite-manager.sh aliases
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-add <project>
bash {baseDir}/scripts/alias-favorite-manager.sh favorite-remove <project>
bash {baseDir}/scripts/alias-favorite-manager.sh favorites

Aliases are case-insensitive and are resolved by /find, /switch, and project-fingerprints.sh name queries.

Entire Integration

Run Entire CLI commands in a registered project context:

/entire-status <project> [root|--root <root>]
/entire-enable <project> [root|--root <root>] [--agent <name>] [--strategy <name>]
/entire-rewind-list <project> [root|--root <root>]

Shell equivalent:

bash {baseDir}/scripts/entire-manager.sh status <project> [root|--root <root>]
bash {baseDir}/scripts/entire-manager.sh enable <project> [root|--root <root>] [entire enable flags...]
bash {baseDir}/scripts/entire-manager.sh rewind-list <project> [root|--root <root>]

Defaults:

• entire enable defaults to --agent claude-code --strategy manual-commit when not provided.
• /entire-rewind-list uses non-destructive JSON listing (entire rewind --list).

Schema

{
  "schema": "osori.registry",
  "version": 2,
  "updatedAt": "2026-02-16T00:00:00Z",
  "roots": [
    {
      "key": "default",
      "label": "Default",
      "paths": []
    }
  ],
  "aliases": {
    "rh": "RunnersHeart"
  },
  "projects": [
    {
      "name": "string",
      "path": "/absolute/path",
      "repo": "owner/repo",
      "lang": "swift|typescript|python|rust|go|ruby|unknown",
      "tags": ["personal", "ios"],
      "description": "Short description",
      "addedAt": "YYYY-MM-DD",
      "root": "default",
      "favorite": false
    }
  ]
}

Auto-trigger Rules

• "work on X" / "X 프로젝트 작업하자" → switch X
• "find project X" / "X 찾아줘" / "X 경로" → registry search or discover
• "list projects" / "프로젝트 목록" → list
• "add project" / "프로젝트 추가" → add
• "project status" / "프로젝트 상태" → status all