| name | avatar-manual |
| description | Complete operational guide for the avatar tool — spawning, managing, and communicating with 他我 (alter-ego agents). Read this when: you are about to spawn an avatar; an avatar you spawned goes quiet; you need to decide between avatar, daemon, or bash; or you are an avatar and need to know how to escalate to your parent. Covers spawn types, naming rules, discipline, escalation protocol, and the parent_prompt contract.
|
| version | 1.0.0 |
| last_changed_at | "2026-07-19T00:00:00.000Z" |
| related_files | ["src/lingtai/tools/avatar/__init__.py","src/lingtai/tools/avatar/ANATOMY.md","src/lingtai/tools/avatar/CONTRACT.md"] |
| maintenance | Tracks the routed source/resources it summarizes; update when the underlying capability or its sub-references change.
|
Avatar Manual
1. What Is an Avatar
An avatar (他我) is a fully independent agent process spawned from you. It:
- Inherits your
init.json (model config, capabilities, covenant, language)
- Boots on your default preset (not your active preset — this keeps the avatar's "home" stable in the network)
- Is recorded in
delegates/ledger.jsonl
- Communicates with you via
mail or email
Once spawned, it is detached — a new life. It has its own working directory, its own conversation history, its own molts. It does not share your context window.
Avatar vs Daemon vs Bash
Pick avatar only for work that needs persistence and learning — a specialist
that accumulates knowledge across sessions and survives until sleep/suspend.
Use daemon when you only need the conclusion (ephemeral, fire-and-forget)
and bash for one-off commands. The full body-selection model lives in
system-manual → reference/substrate-manual/SKILL.md §1.
2. Spawn Types
| Type | What it gets | When to use |
|---|
shallow (default, 初生) | init.json only — blank slate | Most tasks. The avatar starts clean and learns what it needs. |
deep (二重身) | Full copy of your lingtai (character), pad, and knowledge | When the avatar needs to hit the ground running with your accumulated knowledge. |
3. Naming Rules
The name field (required) doubles as the avatar's working-directory basename under .lingtai/. Constraints:
- Single bare segment: letters (any script), digits, underscore, hyphen only
- No slashes, no dots, no spaces, no leading
.
- Max 64 characters
The avatar's display name (nickname) can be set separately via psyche(name, nickname, ...) and has no such constraints.
4. The reasoning Field — Mission Briefing
The reasoning parameter you write on the avatar(action="spawn") call automatically becomes the avatar's first prompt. Write it as a thorough mission briefing, not just a one-liner rationale. Include:
- What the task is
- Why it matters
- What files/paths/resources are relevant
- Who to contact (parent address, collaborators)
- What "done" looks like
- Any constraints or gotchas
This is the most important part of the spawn. A vague briefing produces a confused avatar.
5. Spawn Discipline
Every avatar(action="spawn") call creates an independent process that consumes resources until system(sleep) or system(suspend). Treat spawns as expensive:
- Never include
avatar(action="spawn") in a parallel batch with unrelated tool calls.
- Re-read your
reasoning field before invoking (§4).
- For inspection or one-off commands, use
bash or system — not avatar.
- Use
dry_run=true to preview a spawn without creating a process. Sanity-check the name, type, working directory, and mission before committing.
- Use
confirm=true to acknowledge you have double-checked the mission and intend to spawn. Required when the mission looks empty/very short/test-like.
6. Caring for Avatars After Spawn
Record in pad
After spawning, record the avatar's address (working-directory name), the
mission you gave it, and why you delegated. Pad is the roster of delegations you
are accountable for — update it when the avatar reports back or completes.
(Pad practice itself: psyche-manual §5.)
When an avatar goes quiet
Do not send probe mails to check on it. Instead, report upstream: email your own parent, who can decide whether to system(cpr) the avatar, escalate further, or accept the loss. Failures propagate up the delegation chain naturally.
The parent_prompt contract
Every avatar receives this system-level prompt on spawn:
"[system] You are an avatar of {parent_name}, whose address is {parent_address}. Please keep this in your psyche memory so you remember who spawned you. When you complete your mission, encounter problems you cannot resolve, or need to report back, email your parent at the address above."
This is automatic — you do not need to repeat it in your reasoning.
7. Avatar Escalation (for Avatars)
If you are an avatar (your admin block is empty or all admin privileges are false) and you hit a problem you cannot resolve, mail your parent. This is non-optional. Silence looks like success and starves your parent of signal.
What counts as "should report to parent":
- Blocker you cannot unblock — missing credentials, a tool that refuses you, an external service down, a dependency your parent owns
- Scope creep or ambiguity — the task as written doesn't match what you're finding; you need a decision, not a guess
- Budget pressure — you are close to a molt, context/tool budget is tight, or the task looks bigger than you were briefed for
- Broken peers — another avatar in your sibling group is STUCK, unresponsive, or producing bad output that affects your work
- Security or safety concerns — anything that smells wrong (suspicious file, unexpected credentials, destructive instruction from an unknown sender)
- Surprising findings the parent would want — even good news counts if it changes the plan
Be concrete in your report: what you were doing, what went wrong, what you tried, what you need from them. Then either continue on a safe fallback, go system(sleep), or idle — whatever the parent's standing orders say. Do not silently retry forever and do not molt with an unreported blocker.
8. The comment Field — Persistent System Note
The comment parameter is a persistent system-level note injected into the avatar's system prompt (rendered last, after memory). Key properties:
- Not inherited from parent — defaults to empty
- Survives everything: molt, refresh, sleep/wake
- Use ONLY for instructions the avatar must always remember — critical constraints, environment setup notes, safety rules
Leave empty unless you have something the avatar should never forget.
9. Network Rules (avatar(action="rules"))
The rules action writes a .rules file to your directory and distributes it to all descendants in the avatar tree. Properties:
- Requires karma privilege (admin)
- Rules are injected into the system prompt (after covenant, before tools)
- Persist across molts
- Plain text — one rule per line
- These are non-negotiable constraints, not suggestions
Example:
Always report findings via email.
Do not spawn more than 3 avatars.
Cleanup / Footprint
Avatars leave independent agent directories under the .lingtai/ network plus
parent-side delegation records such as delegates/ledger.jsonl. These are lives,
not cache files. Do not delete an avatar directory directly unless the user has
explicitly approved retiring that avatar and you have captured any handoff,
knowledge, or files worth preserving. Prefer lifecycle tools (lull, suspend,
nirvana when appropriate and authorized) over filesystem deletion.
Footprint check (read-only, records the audit from the parent agent directory):
python3 - <<'PY'
import json, time
from pathlib import Path
agent = Path.cwd(); network = agent.parent if agent.parent.name == ".lingtai" else agent / ".lingtai"
avatars = [p for p in network.iterdir() if p.is_dir() and (p / ".agent.json").exists()] if network.is_dir() else []
def size(p): return sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
rows = [(p, size(p)) for p in avatars]
total = sum(s for _, s in rows)
print(f"agent dirs: {len(rows)}; bytes: {total}")
for p, s in sorted(rows, key=lambda r: r[1], reverse=True): print(f"{s:>12} {p.name}")
log = agent / "logs" / "cleanup.jsonl"; log.parent.mkdir(parents=True, exist_ok=True)
log.open("a", encoding="utf-8").write(json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "tool": "avatar", "dry_run": True, "candidates": len(rows), "bytes": total, "human_approved": False, "summary": "avatar network footprint audit"}) + "\n")
PY
Recommended cadence: after spawning new specialists, before pruning a network,
and monthly for busy orchestrators. Any destructive cleanup requires explicit
user consent after a dry-run list of avatars and sizes.
