Shiba Studio documentation

Getting started

Requirements: Node.js ≥ 22.5 and Git. The runs/audit database uses Node's built-in node:sqlite — nothing to compile on any platform. Runs on Windows, macOS, and Linux.

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, 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 — 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.
• Quota — the QUOTA pill reports live spend against your monthly budget from Settings.
• 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.

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 30+ 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

• Cron schedules per agent, with plain-language descriptions and per-schedule instructions.
• Headless operation — schedules arm at server start and fire 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 is browsable per schedule.
• Self-cleaning — deleting an agent retires its schedules automatically; runs from deleted agents show a 🛸 avatar in logs.

Capabilities

• Integrations: GitHub (repos, issues, PRs), Slack, Google Drive, Discord, X (post + read timeline), and Obsidian (vault-aware notes). Scopes are granted per-agent.
• 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.

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.