ArTchie Studios
ArTchie-Bedder-Suite / Docs / ArTchie AI

ArTchie AI Guide — companion mind

Plain English first. Sharp edges after.

1. What this is / is not

ArTchie AI (brand: ArTchie-AI / ArTchie.AI) is the in-Editor companion chat for an ArTchie-equipped Unity project. It owns the conversation, injects the ArTchie Intelligence Protocol into every exchange, and owns the tool loop any brain can drive — so the tools never have to be re-taught on every brain. Package: com.artchie.ai (unity-artchie-ai). Unity 2021.3+. Editor-only. Window title: Chat (menu ArTchie / AI / Chat).

It is not Atlas (the project map — AI uses Atlas when both are present). It is not Charter / Scribe polish (those kits have their own optional brains). It is not a place that asks you to paste an API key. It is not MCP. Soft pair: Atlas is optional. Map tools (AtlasApi Search/Trace/Snippet/Architecture/DeadMethods) compile behind #if ARTCHIE_ATLAS (Core syncs that define from the Atlas kit folder; versionDefines also sets it if Atlas is still a UPM package). Chat, CLI backends, and the ArTchie tool loop work without Atlas — Atlas calls return kit not loaded. Soft/optional: Unity AI Assistant (com.unity.ai.assistant), gated by versionDefines → UNITY_AI_ASSISTANT. CLI backends (Claude Code, Grok Build) work without Unity AI. The ArTchie tool loop still works when Unity AI is absent.

2. Open it

Everything hangs under:

ArTchie / AI / Chat

Job Click
Open companion chat ArTchie / AI / Chat

Window tab is Chat (matches the last menu segment). Debug items under ArTchie / AI / Debug / … are Editor diagnostics, not the Chat path.

If a README still says Tools / ArTchie AI / Chat without the ArTchie / AI / … shape, the README is stale — trust the menu in Unity (MenuItem("Tools/ArTchie/AI/Chat")).

3. First five minutes

  1. Add com.artchie.ai under Assets/ArTchie Studios/ArTchie-AI/. Atlas (com.artchie.atlas under ArTchie-Suite) is optional — add it if you want map tools. Open Unity. Wait for import. Check the Console for red errors.
  2. Optional but recommended: click ArTchie / Atlas / Rebuild Index once so the project map exists before you ask code questions.
  3. Click ArTchie / AI / Chat. You should see a backend dropdown, a Loop dial (Native | ArTchie), Clear, a ⚙ gear, a transcript area, a multiline input, and Send.
  4. Leave the backend on UnityAssistant if you have com.unity.ai.assistant, or switch to ClaudeCode / GrokBuild if those CLIs are on your PATH (or click Detect paths in ⚙). Unity Assistant: Loop can be Native or ArTchie (Native is never hidden). Claude / Grok: Loop is forced ArTchie. Status line on the right says which brain is live (or “Unity AI absent …” / “CLI · Missing — Detect paths…”).
  5. Type a short question about this project (example: “What does the player controller do?”). Click Send. Wait for the whole reply (no streaming in v0.1). On the ArTchie loop, a tool call shows as a chip in the transcript — not a second You card. Read it. Click Clear if you want a fresh transcript (Clear also drops CLI resume ids).

That is enough. No pasted key. Gear settings are extras.

4. The meat

What the window does

  • Backend dropdown — UnityAssistant · ClaudeCode · GrokBuild. Stored in EditorPrefs ArtchieAi.Backend.
  • Loop dial — Native · ArTchie. Label Loop. Pref ArtchieAi.LoopMode (default Native). Unity Assistant: both choices, Native never hidden (tooltip: Native = her tools, ArTchie = chips here). Claude Code / Grok Build: dial forced ArTchie and Native is disabled (tooltip: Loop forced ArTchie; Native is Unity-only). Switching backend does not wipe your Unity Loop choice.
  • Clear — wipes the in-memory transcript, message cards, tool chips, and CLI session resume ids. Cancels an in-flight Ask wait. Does not touch project disk.
  • ⚙ — toggles the settings pane (Unity AI approve dials + CLI binary paths + Detect paths). The ArTchie loop reads Third-party + Auto-run from here.
  • Send — runs one turn. Status shows thinking… while busy, or waiting for Approve… on an Ask chip. Replies land as cards in this window (Unity Assistant replies do not go to Unity’s own Assistant window).
  • Empty / first-run (no transcript): title No chat yet. Info HelpBox: pick a brain (Unity Assistant, Claude Code, or Grok Build) → type a project question → Send; Loop dial Native or ArTchie (Native is Unity Assistant only and stays on the dial; Claude/Grok force ArTchie); Atlas is optional — Rebuild Index once if you have the kit; Prefer Detect paths (⚙) over typing a binary by hand; no pasted API key. When Atlas is missing the HelpBox says map tools stay off and chat still works. Extra Warning when the selected optional brain is absent (Unity AI / CLI Missing). miniLabel ArTchie / AI / Chat · Atlas: ArTchie / Atlas / Rebuild Index (or “Atlas not installed”). Clear restores the empty panel.

Protocol (every turn)

Every exchange rides the ArTchie Intelligence Protocol:

  1. Prefer file: Assets/ArTchie Studios/AI-Bridge/AssistantGuidelines.txt (TextAsset) when the project has one.
  2. Else a built-in fallback that tells the brain it is ArTchie AI inside an ArTchie project: prefer Atlas tools (Search / Trace / Snippet / Architecture / DeadMethods) and honest text search for comments/strings/docs/live scene state; BedderScript is “BS”, never “BC”; studio name is ArTchie.

You do not paste the protocol into the chat — the wrapper injects it.

On the ArTchie loop, the first prompt also gets the compact Manifest + the one-fence rule (see Tool loop). Native Unity stays Protocol only.

Tool loop

ArTchie-AI owns the in-Editor tool loop. Any brain can drive it. Atlas tools register once ([AgentTool] / [ToolParameter]). There is no second registry. No MCP. No pasted API key.

Loop dial: Native | ArTchie

Brain What you get
Unity Assistant Both choices. Native is never hidden.
Claude Code / Grok Build Forced ArTchie. Native greys out. Pref keeps the Unity choice so switching back restores it.

Native (Unity only) = Unity’s own LlmAgent + WithToolsFrom<Atlas.AtlasAssistantTools> + RunHeadless. Her loop, her approvals, her credits. We cannot chip her calls — no public API, and we do not scrape her window. One shot: You card + AI card. Done.

ArTchie = our parse loop on the model’s text reply. Unity-when-ArTchie does not use WithToolsFrom (that would skip our Gate / chips) and does not fake a CLI.

What the ArTchie loop does

On Send (SendArtchieLoop):

  1. First prompt is stuffed with ArtchieLoopPreamble(): Intelligence Protocol + compact Manifest JSON (tool ids + arg name/type; descriptions clipped) + one rule: To call a tool, emit ONE fenced JSON block {"tool":"...","args":{...}} and stop; wait for {"tool":...,"result":...} as the next user turn; final answers have no tool fence.
  2. Brain replies. Wrapper TryParses.
    • No fence → that text is the final answer. Append. Stop.
    • Malformed fence → one retry (parse error as the next user turn). Still malformed → notice chip malformed tool call + last text. Stop.
    • Valid call → count a tool round. If the count would pass 8, notice chip tool call cap (8); last model text stays visible; the 9th fence is not executed.
  3. Gate reads the ⚙ Third-party dial (AIAssistant.ThirdPartyToolPolicy: Allow / Ask / Deny) plus Auto-run. Auto-run collapses Ask → Allow. Deny always stays Deny. v0: every ArTchie / Atlas tool is Third-party.
  4. A chip lands in the transcript (not a You card). Turn #n increments. Allow runs now. Policy Deny refuses now (denied by approve mode). Ask paints Approve / Deny and waits — nothing runs until you click.
  5. Result is wrapped as an envelope and sent as the next user turn. Resume (CLI --resume with the envelope only; Unity ArTchie = another RunHeadless with transcript + envelope). Repeat until a final answer or cap 8.

Visual You / AI cards are the original user message + the final (or last) assistant text. Fences and envelopes still live on the internal transcript so Continuity fallback can see them.

Ask chip

  • Status: waiting for Approve…. Send stays busy.
  • Approve → execute → chip ok or error → envelope → resume.
  • Deny → chip denied → envelope "denied by user" → resume (the brain is told no; the loop does not halt).
  • Clear cancels the wait. Do not click Send again until the wait ends or you Clear.

Manifest

Compact JSON from ArtchieToolManifest.BuildCompact() goes into first-turn / ComposeCliPrompt / Unity ArTchie systemPrompt. Native Unity systemPrompt stays Protocol only (no Manifest, no fence rule).

Pretty dump (vet): ArTchie / AI / Debug / Dump Tool Manifest — source tag typecache or fallback.

When Unity AI is present, TypeCache lists every [AgentTool] it can see (Atlas five + extras). When the Assistant package is missing, Manifest fallback is the five Atlas ids only:

  • ArTchie.Atlas.Search
  • ArTchie.Atlas.Trace
  • ArTchie.Atlas.Snippet
  • ArTchie.Atlas.Architecture
  • ArTchie.Atlas.DeadMethods

Extras (ArTchie.Bedder.CensusCompact, ArTchie.Bedder.ValidateJson, ArTchie.Anvil.AgentProjectDump, ArTchie.Rivet.SceneQuery) need the Assistant package to compile in and show up in TypeCache. They may be absent from the fallback Manifest. Honest: the ArTchie loop still runs without Unity AI (CLI + Atlas five).

Honest limits (loop)

  • Not smoked on the 66 rig yet. Do not claim a live Architecture → Ask Approve → answer transcript from this disk.
  • Native-loop chips: none. We cannot see her tool stream.
  • Unity ArTchie: if she only returns prose, TryParse sees no fence → final answer, no chips. We do not invent a Unity tool stream.
  • CLI sessions minted before Manifest-in-prompt do not get the Manifest restuffed until Clear / a new session. Do not auto-clear (Continuity rule).
  • Cap is 8 tool rounds per user Send.
  • No MCP. No --continue. No --always-approve. No arbitrary C# exec tool.

Continuity

CLI brains keep a session so later turns do not re-paste the whole prompt.

Backend First turn Later turns JSON id / text
Claude Code claude -p --output-format json --session-id <uuid> <firstPrompt> claude -p --resume <id> --output-format json <onlyNewText> .session_id · .result
Grok Build grok -p <prompt> --output-format json --session-id <uuid> --cwd <projectRoot> --verbatim grok -p <onlyNewText> --output-format json --resume <id> --cwd <projectRoot> --verbatim .sessionId · .result then .text then .response

Never --continue. That would attach to an interactive terminal session in the project cwd. Never MCP. Never a pasted API key.

Ids live in EditorPrefs ArtchieAi.ClaudeSessionId / ArtchieAi.GrokSessionId. Clear drops both. Backend switch does not. If JSON parse / resume fails that turn: warning in the Console, drop that backend’s id, fall back to transcript-in-prompt (budget about 9000 characters; older text is truncated with a leading …).

Unity Native is one RunHeadless. Unity ArTchie resume is another RunHeadless(TranscriptBlock + User: envelope) — not CLI --resume.

No streaming — the reply arrives whole. CLI processes have a 180s timeout.

Backends

Backend What it runs Needs
UnityAssistant Native: headless LlmAgent (uniqueId ArTchie.AI.Wrapper) + Protocol + Atlas tools via WithToolsFrom when Atlas is present. ArTchie: second agent ArTchie.AI.Wrapper.Loop, Manifest in system prompt, no WithToolsFrom, parse her text. com.unity.ai.assistant (define UNITY_AI_ASSISTANT). Atlas optional.
ClaudeCode Spawns claude as above. Always ArTchie loop. claude on PATH, or EditorPrefs ArtchieAi.ClaudePath
GrokBuild Spawns grok as above. Always ArTchie loop. grok on PATH, or EditorPrefs ArtchieAi.GrokPath

CLI backends work without Unity AI and without Atlas. Without Unity AI installed, picking UnityAssistant returns a clear message: switch backend or install com.unity.ai.assistant. The ArTchie loop on Claude / Grok still works. Atlas tools return kit not loaded until the Atlas kit is present.

Gear: Unity AI approve mode

When Unity AI is present, the ⚙ pane writes the Assistant’s own EditorPrefs (live on every tool call):

  • Auto-run — skip every Ask prompt (AIAssistant.AutoRun)
  • Policies (Allow / Ask / Deny): third-party tools, Unity built-in tools, run generated code, read project files, modify project files

These are the Assistant’s preferences — they also apply in Unity’s own Assistant window. Defaults lean Ask for third-party / code exec / modify; Allow for first-party / read.

The ArTchie loop reads Third-party + Auto-run at our execute point. Native Unity uses her full set of dials inside her agent. Loop dial: Native is Unity Assistant only. Claude / Grok always use the ArTchie loop. Native is never hidden for Unity.

Gear: CLI paths

Empty path = binary name from PATH (claude or grok). Override only if your install is not on PATH. Detect paths scans PATH + common home bins (.grok/bin, .local/bin, …) and fills Found hits. Status stays claude: Found|Missing · grok: Found|Missing. Missing = optional brain only — install that CLI, Detect again, sign in; other brains still work where installed. Never a field for pasting an API key into this Guide or this window.

Missing optional brain (HelpBox)

  • Atlas not installed: Info HelpBox — optional map kit; Search/Trace stay off; chat still works. Install com.artchie.atlas when you want the project map.
  • Unity AI absent: Warning/Info HelpBox — not in this project (com.unity.ai.assistant); optional brain unavailable; switch to Claude/Grok (Detect paths) or install Unity AI — no key needed. ArTchie loop on CLI still works.
  • CLI not found: Warning HelpBox + status Missing — click Detect paths (or type the binary path), then sign in; other brains still work where installed — no pasted key.
  • Prefer Detect CLIs over pasting a key. Chat without optional packages stays usable with any installed brain.

Soft Unity AI

ArtchieAi.Editor.asmdef gates Assistant types with:

com.unity.ai.assistant >= 0.1.0 → UNITY_AI_ASSISTANT

References list Atlas.Editor (soft — types behind #if ARTCHIE_ATLAS) plus Assistant assemblies (only used under UNITY_AI_ASSISTANT). Mechanical Atlas menus never need this package. Companion chat without Unity AI = CLI backends + ArTchie loop. Companion chat without Atlas = same, minus map tools.

Soft pair: Atlas

Atlas and ArTchie AI work together when both are present and do not require each other. Core sets ARTCHIE_ATLAS when the Atlas kit folder is on disk. AI’s Atlas call sites stay the original Atlas.AtlasApi.* / WithToolsFrom<Atlas.AtlasAssistantTools> bodies, wrapped in #if ARTCHIE_ATLAS. Atlas alone never requires ArTchie AI or a pasted key.

5. Common stuck

  1. Menus say Tools / ArTchie AI / … — stale README. Trust Unity: ArTchie / AI / Chat.
  2. I don’t see ArTchie / AI — package not imported, asmdef error, or wrong project. Check Console and Assets/ArTchie Studios/ArTchie-AI/com.artchie.ai. Atlas is optional.
  3. Status: “Unity AI absent …” / HelpBox — optional. Switch backend to Claude Code or Grok Build (Detect paths in ⚙), or install com.unity.ai.assistant. Mechanical Atlas still works either way. ArTchie loop on CLI still works.
  4. CLI · Missing / ✗ … not found — binary not on PATH. Open ⚙ → Detect paths (or type Claude / Grok path), then sign in. Prefer Detect over pasting a key.
  5. CLI timed out — long thinking hits the 180s cap. Shorter question, or run the CLI outside Unity once to confirm auth/network.
  6. Answers ignore the project map — rebuild Atlas (ArTchie / Atlas / Rebuild Index). On Native Unity, Atlas tools ride WithToolsFrom. On the ArTchie loop, the compact Manifest is in the first prompt — if the brain never emits a fence, you get prose only (Unity ArTchie especially).
  7. Chip stuck on pending / status “waiting for Approve…” — ⚙ Third-party is Ask. Click Approve or Deny on the chip. Nothing runs until you do. Clear cancels the wait.
  8. Notice chip “malformed tool call” — the model’s fence was not valid JSON {"tool","args"}. One retry already happened. Ask again in plainer words, or Clear and start a new session.
  9. Notice chip “tool call cap (8)” — eight tool rounds this Send. Last text is kept. Ask a narrower question, or Clear.
  10. Bedder / Anvil / Rivet tools missing — Unity AI package absent, so extras are not in the fallback Manifest (five Atlas ids only). Install com.unity.ai.assistant or stay on Atlas tools.
  11. Someone asked for a pasted API key — wrong product copy. This kit never requires a key in the chat window. Auth for CLIs lives with the CLI install; Unity AI uses Unity’s own account flow.

6. For pros

Package + asmdef

com.artchie.ai · ArtchieAi.Editor · rootNamespace ArtchieAi
references: Atlas.Editor (soft), Unity.AI.Assistant.Runtime, Unity.AI.Assistant.API.Editor
includePlatforms: Editor
versionDefines: com.unity.ai.assistant >= 0.1.0 → UNITY_AI_ASSISTANT
                com.artchie.atlas >= 0.0.1 → ARTCHIE_ATLAS (UPM leftover; Assets kits use Core sync)
MenuItem: Tools/ArTchie/AI/Chat → ArtchieAiWindow ("Chat")
Loop: Native | ArTchie (ArtchieAi.LoopMode). Claude/Grok force ArTchie.
Send: Native → SendNative → SendUnityAi (LlmAgent + WithToolsFrom)
      ArTchie → SendArtchieLoop (TryParse → Gate → chip → FormatResult → Dispatch resume; cap 8)

EditorPrefs

Key Meaning
ArtchieAi.Backend 0 UnityAssistant · 1 ClaudeCode · 2 GrokBuild
ArtchieAi.LoopMode Native (default) | ArTchie
ArtchieAi.ClaudePath override claude binary
ArtchieAi.GrokPath override grok binary
ArtchieAi.ClaudeSessionId Claude --resume id (Clear drops)
ArtchieAi.GrokSessionId Grok --resume id (Clear drops)
AIAssistant.AutoRun / AIAssistant.*Policy Unity Assistant approve dials (shared with her window). ArTchie Gate reads Third-party + Auto-run.

Constants (code)

  • Guidelines path: Assets/ArTchie Studios/AI-Bridge/AssistantGuidelines.txt
  • Transcript prompt budget: 9000 chars
  • CLI timeout: 180000 ms
  • Tool-round cap: 8 (MaxToolRounds)
  • Agent id (Unity Native): ArTchie.AI.Wrapper
  • Agent id (Unity ArTchie): ArTchie.AI.Wrapper.Loop
  • Fence: one block {"tool":"...","args":{...}} · envelope {"tool":...,"result":...}
  • Compact Manifest clip: descriptions ~140 / arg ~72
  • Dump menu: ArTchie / AI / Debug / Dump Tool Manifest

Design bounds (do not invent)

  • Brand in user-facing copy: ArTchie AI / ArTchie-AI / ArTchie.AI — never old companion names.
  • Never require a pasted API key for hatch/chat.
  • No MCP. No --continue. No --always-approve. No third kit. Soft Unity AI only.
  • Native never hidden for Unity Assistant. Claude / Grok always ArTchie.
  • Native-loop visibility: none (no public API). Do not scrape her window.
  • Not claimed: smoked on 66 rig. Extras may be absent from fallback Manifest when Assistant package is missing.

Canonical base

artchie-RECONCILED-20260822-2107. Package README + this Guide. Suite contract: Atlas + AI are a soft pair (#if ARTCHIE_ATLAS). Loop shape: hive artchie-ai-tool-loop (notes/SEND-V0.md, ASK.md, LOOP-NOTES.md).

Kit When you want it
Suite Map Which ArTchie pile does what · Guides/Guide-Suite-Map.md
Atlas Project map / search / graph / trace — optional; map tools when present
Scribe / Charter Comments + game plans with their own optional brains (None first)
Folio Read markdown notes in the Editor
Anvil / Rivet Health audits / daily chores — not companion chat
Bedder In-player IDE (may probe Atlas / Unity AI by reflection only)

Install Atlas. Open ArTchie / AI / Chat. Pick a backend. Send one question. No pasted key.

Source in the box: Assets/ArTchie Studios/ArTchie-AI/com.artchie.ai/Documentation/Guide-Artchie-AI.md