Shiba Studio documentation

Getting started

Requirements: Node.js ≥ 22.5 and Git for a source install. The runs/audit database uses Node's built-in node:sqlite — nothing to compile on any platform. Runs on Windows, macOS, and Linux. Compiled Windows and macOS apps are double-clickable, bundle Studio themselves, and update when main or development moves.

Windows (PowerShell)

# prerequisites
winget install OpenJS.NodeJS.LTS
winget install Git.Git

# install & run
git clone https://github.com/stevologic/shiba-studio.git
cd shiba-studio
npm install
npm run dev

macOS (Terminal)

brew install node git
git clone https://github.com/stevologic/shiba-studio.git
cd shiba-studio && npm install && npm run dev

Linux (any distro, via nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
git clone https://github.com/stevologic/shiba-studio.git
cd shiba-studio && npm install && npm run dev

Open http://localhost:3000. For production mode, run npm run build && npm run start — scheduled automations keep firing as long as the server is up, no browser needed.

Connect a model source

Open Settings and connect any one of the four routes. The top bar shows a live readiness badge for each.

Set a default model and a default workspace in Settings, then press New Chat.

Grok Chat

Chat is a working surface, not just a conversation: it streams reasoning, renders markdown with syntax highlighting and rich cards, shows images inline (click for a lightbox), accepts drag-and-drop / pasted attachments, and can act on your repo, your vault, and the web.

• Sessions live in a collapsible, searchable rail on the left; each keeps its own model, target, reasoning effort, workspace, and history. New chats are auto-titled by a low-cost model after the first exchange.
• Chat targets — talk to plain Grok, to a specific agent (with its personality and live integration context), or to all agents at once with a synthesized answer.
• Models & reasoning — fresh installs default to Grok 4.6 (500k context). Switch cloud/local models per session from the composer pill; reasoning-capable models get an effort selector (off/low/med/high). A terminal toggle routes the session through the local Grok CLI instead of the API.
• Message queue — keep typing while a reply streams; up to 20 messages queue and fire in order when the turn settles. Stick-to-bottom tracks growing reasoning.
• Rich cards — a fenced shiba-card JSON block becomes live stats, progress, checklists, timelines, callouts, media, sparklines, bars, or multi-series timecharts. Malformed payloads fall back to code, never losing content.
• Stream resilience — long tool-using turns get extended timeouts; HTML/proxy dumps and aborts normalize to short user-facing recovery text.
• Quota — the QUOTA pill reports live spend against your monthly budget from Settings.
• Keyboard shortcuts — press ? or Ctrl/⌘+/ for the studio cheatsheet (palette, terminal, slash commands, Code IDE). Ctrl+K stays the command palette.
• Housekeeping — export any conversation as Markdown (with reasoning and token counts), edit-and-resend your messages, regenerate the last answer.

Slash commands

Type / in the composer for an autocomplete menu (↑↓ navigate, Tab/Enter complete, Esc dismiss). Commands run instantly and post their result into the chat:

Git commands run against the chat's bound workspace when one is set, otherwise the linked project's workspace or the default workspace. PRs use your GitHub token from Capabilities.

Chat workspaces — give a conversation a folder

Bind a chat to any folder on disk — typically a cloned GitHub repo — and the conversation gains hands:

1. Click the Workspace button in the chat top bar (or type /workspace).
2. Browse to the folder — git repositories are badged and sorted first — or type its path, then Use this folder.
3. Grok in that chat now has real filesystem tools (fs_list, fs_read, fs_write, fs_search) rooted in that folder, and /git commands run against it.

Ask things like "read src/api.ts and explain the auth flow", "find every usage of the deprecated helper", or "fix the typo in the README and commit it" — the model explores and edits the actual files instead of guessing. The binding persists with the session, shows in the top-bar chip, and detaches with one click (or /workspace off).

Annotation sub-browser

Refine code by pointing at the page:

1. Type /annotate (or click the crosshair in the composer) and enter your dev server's URL, e.g. http://localhost:5173.
2. Interact mode — clicks pass through to the live page: follow links, press buttons, and scroll with your mouse wheel to reach the screen you care about.
3. Annotate mode — click any element; it's selected DevTools-style and outlined orange in a fresh screenshot.
4. Add a note ("make this container a responsive 2-column grid") and Send to chat — the composer receives the element's selector, size, and HTML excerpt plus the highlighted screenshot.

It drives a real headless Chrome (no window ever appears), so it works with any URL — cross-origin dev servers included.

Meetings

Meetings turns an agent into a colleague you sit down with. Hold a spoken project review: the agent leads — presenting what it has been building — while you steer with Grok Voice 2.0 or text. Turns stream over SSE; the room has a visual stage and a conversation rail.

• Grok Voice 2.0 — grok-voice-think-fast-2.0 for listening and spoken replies (ephemeral token; the API key stays on the host). Browser speech + TTS is the fallback.
• Stage visuals — real workspace code excerpts (never model-invented), SVG diagrams, markdown notes, and live screenshots via the studio browser. Recent visuals stay in context so “explain this” works.
• Steering — AI suggestion chips each turn; annotate the stage with a sketch layer and share markup into the transcript.
• Minutes — end the meeting for summary, direction, decisions, and todos. Confirm to create Board cards (idempotent); deleting a meeting never deletes those cards.
• Privacy — no Live Meeting audio is stored; only text turns reach the server.

Grok phone assistant

Call the Voice Agent Builder number and dictate Studio commands. Settings issues a one-time shiba_phone_ bearer; Grok invokes the public MCP/command URL and Shiba creates Board cards, runs git, remembers facts, or starts durable work. Incoming SIP webhooks can join the same tool session.

Board

The Board is the shared Kanban for people and agents. Cards can be created manually, assigned to an agent, started as agent work, and tracked through Backlog, Todo, In Progress, In Review, Done, or Cancelled.

• Timeline (Gantt): open Timeline for a delivered-work chart of Done cards under the current project filter (created → done from activity).
• Linear sync: connect a Linear API key, choose a team, and pull, push, or two-way sync Board cards with Linear issues.
• Jira sync: connect a Jira Cloud site, email, and API token, then target a project or Jira Kanban board.
• Modes: sync task fields only, or task fields plus workflow status/columns.
• Grok Files snapshots: optional private backup of safe card fields through xAI Files (send/pull; never deletes local-only cards or live work).
• Boundaries: Shiba Studio keeps stable SHIB-# refs and syncs title, description, status, and provider links; ordering, assignees, runs, sprints, activity, and deletions stay local/provider-native.

Code IDE

The Code page is a Monaco workspace on your machine: multi-file tabs, repository search, structured Git staging/branches/history, GitHub PRs/issues/actions, diagnostics, and the real host terminal. Open the default workspace, a Project folder, or a discovered git worktree from the picker.

Artifact Studio

Treat generated HTML, PDF, and Office files as first-class objects: immutable checkpoint-backed previews, visual evidence, anchored annotations, rollback, and revocable publishing.

Learning & Memories

Agents automatically recall relevant local knowledge before runs and can extract durable facts, decisions, procedures, preferences, and lessons afterward in Review or Automatic mode. The Memories page provides search, approval, editing, pinning, archiving, scope moves, provenance, and deletion.

Agents

Agents are autonomous workers, each with its own model, workspace, git worktree, integration scopes, skills, peers, and persistent memory.

• Local agents run on your machine with the full toolbelt: files, shell, a controlled headless Chrome, web research, image generation, Obsidian, GitHub PRs, and 40+ tools total (browse the live catalog on the Capabilities page).
• Cloud agents run against Grok cloud services and connected cloud integrations only — no access to this machine.
• Skills shape personality and procedure; custom skills are authored in-app and injected into prompts.
• Peers let agents message each other and fan out work.
• Memory — agents persist facts in SQLite and recall them in later runs; chat shares the mechanism via /remember.

The Agents page is where you create, edit, and view agents; running them and reading execution traces happens on the Automations page. Every run — prompt, tool calls, side effects, outcome — is stored with full provenance, and clicking a run-log entry opens a detail modal.

Automations

• Durable definitions — recurring cron, one-time, webhooks, integration events, filesystem watches, and health checks; each names an agent as execution owner.
• Headless operation — the Automation engine arms at server start and fires as long as the server is up; the browser can stay closed.
• Live execution traces — watch each step (thought → tool call → result) stream as the agent works; run history deep-links to full provenance.
• Self-cleaning — removing an execution owner safely retires its Automations while preserving history.

Capabilities

• Integrations: GitHub (repos, issues, PRs), Slack, Google Drive, Discord, X (post + read timeline), Obsidian (vault-aware notes), Vercel, Netlify, Linear, and Jira. Agent integrations are granted per-agent; Linear/Jira are Board-scoped sync targets.
• Custom skills: reusable prompt procedures you author once and attach to any agent.
• MCP servers: connect Model Context Protocol servers from curated presets or your own commands; their tools join the agent toolbelt.
• Tool catalog: the Capabilities page lists every built-in tool with its description — what agents can actually do, no guessing.

Cloud sync

Sync pushes/pulls your entities through your own xAI account's private file storage — nothing touches any third-party server.

• What syncs: agents, automations, projects, chats, workspace uploads, and local-model settings — each category as one JSON snapshot named shiba-sync-<category>.json.
• Push replaces the previous snapshot; pull merges by id — local items are updated, new ones added, nothing deleted.
• Credentials are never included in snapshots.

Board sync is separate from xAI cloud sync: it mirrors selected Board card fields with Linear or Jira using the credentials you configure in Capabilities.

Configuration

Environment variables

Data locations

Upgrades are automatic: a legacy ~/.grokdesk directory from pre-rebrand installs (including its key and database) is renamed to ~/.shiba-studio on first start, and the old GROKDESK_* env names still work as fallbacks.

Security

• Local-first: zero telemetry; outbound traffic goes only to xAI and the integrations you configure.
• Secrets: AES-256-GCM at rest (enc:v1: prefix); the machine key lives outside the project; plaintext stores migrate to encrypted form on load; secrets are excluded from sync snapshots.
• Audit: every consequential action — runs, chats, config changes, integrations, git, sub-browser — lands in the Logs page with agent/model provenance and CSV/JSON export.
• Know the limits: the dev server has no auth of its own. Treat Shiba Studio as single-user on a trusted machine, or bind 127.0.0.1 and front it with your own auth before exposing it beyond localhost.

Troubleshooting

• "Shiba Studio needs Node.js 22.5+" — upgrade Node (node --version to check). No native modules are involved on any platform.
• No models in the picker — connect a model source in Settings; the top-bar readiness badges show what's live.
• X posting returns 403 oauth1-permissions — set your X app to Read and write, then regenerate the access token & secret (tokens freeze the permission level they were created with).
• Timeline reads fail on X — reading requires at least the Basic API tier; the Free tier only permits posting.
• Stale styles in dev — stop the server, delete .next, restart.
• Anything else — open an issue.