FAQ & Troubleshooting

SidStack requires Node.js 18 or later. We recommend using the latest LTS version. You can check your version with node --version.

SidStack uses pnpm as its package manager. While npm may work for installing the CLI globally (npm install -g @sidstack/cli), the project itself requires pnpm for development. Install pnpm with npm install -g pnpm or via corepack enable.

The desktop app uses Tauri 2.x, which requires Rust and platform-specific dependencies.

macOS: Install Xcode Command Line Tools (xcode-select --install) and Rust (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh).
Linux: Install system libraries: sudo apt install libwebkit2gtk-4.1-dev build-essential libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev.
Windows: Install Visual Studio Build Tools and WebView2.

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "sidstack": {
      "command": "npx",
      "args": ["-y", "@sidstack/mcp-server"]
    }
  }
}

Restart Claude Code and it will automatically discover the MCP server for your project.

Common causes:

• Ensure npx is available (comes with Node.js 18+). Run npx --version to verify.
• Check that you have initialized a project with sidstack init or npx @sidstack/cli init in your working directory.
• Verify your .mcp.json is valid JSON (no trailing commas, correct structure).
• Restart Claude Code after any config changes.

If using npx -y @sidstack/mcp-server, ensure you have Node.js 18+ and a working internet connection for the first run (npx downloads the package). If you prefer offline usage, install globally first:

npm install -g @sidstack/mcp-server

Then update your .mcp.json to use sidstack-mcp as the command instead of npx.

Ensure you have the required dependencies:

1. Install Xcode Command Line Tools: xcode-select --install
2. Install Rust: rustup update stable
3. Clear the build cache: cargo clean in the src-tauri/ directory
4. Run pnpm tauri:dev again

If you see code signing errors, you can skip signing for local development by setting APPLE_SIGNING_IDENTITY="".

This usually means the frontend dev server is not running or has an error.

• Make sure you are running pnpm tauri:dev (not just pnpm dev), which starts both the Vite server and Tauri.
• Check the terminal output for Vite compilation errors.
• Open DevTools in the Tauri window (right-click > Inspect) to check for console errors.
• Try clearing the Vite cache: rm -rf node_modules/.vite and restart.

Run sidstack init in your project root. This creates the .sidstack/ directory structure. Then create knowledge documents:

sidstack knowledge create --type business-logic --title "My Feature"

Available document types: index, business-logic, api-endpoint, design-pattern, database-table, module, governance.

Knowledge documents are Markdown files with YAML frontmatter. The frontmatter contains metadata (type, title, module, tags) and the body contains the actual documentation in Markdown. Example:

---
type: business-logic
title: User Authentication
module: auth
tags: [security, login]
---
# User Authentication
Description of the auth flow...

Quality gates run pnpm typecheck, pnpm lint, and pnpm test before allowing task completion. To resolve failures:

• Run each command individually to see specific errors.
• Fix any TypeScript type errors, linting issues, or test failures.
• Then mark the task as completed again.

Yes, but it is not recommended. Use task_complete with force: true and provide a reason. This logs a governance violation for audit purposes. Use this only in exceptional circumstances.

Tasks follow this lifecycle:
pending → in_progress → completed

Tasks can also be set to blocked (waiting on dependency), failed (could not complete), or cancelled (no longer needed).

SidStack is an open-source AI project intelligence platform that gives Claude Code persistent memory about your codebase. It provides 30+ MCP tools for structured knowledge, impact analysis, task governance with quality gates, a training room for lessons learned, and a ticket queue for external issue intake. All data is stored locally in SQLite — no cloud accounts required.

Yes. SidStack is completely free and open source under the MIT License. The desktop app, CLI, and MCP server are all included. There are no usage limits, no telemetry, and no paid tiers. You can use it for personal projects, teams, and commercial work.

SidStack is currently optimized for Claude Code via the Model Context Protocol (MCP). While the knowledge system and CLI work independently of any AI tool, the MCP server integration is designed for Claude Code. Support for other MCP-compatible tools like Cursor and Windsurf may work if they support the MCP standard, but is not officially tested yet.

All project data is stored in the .sidstack/ directory at your project root. This includes:

• knowledge/ – Knowledge documents
• governance.md – Governance configuration
• principles/ – Governance principles
• skills/ – Agent capability skills
• db/ – SQLite databases (tasks, tickets, sessions)

Simply copy or version-control the .sidstack/ directory. Knowledge documents, governance rules, and configuration are all plain text files. The SQLite database in .sidstack/db/ can be copied while the app is not running.

Remove the .sidstack/ directory and reinitialize:

rm -rf .sidstack
sidstack init --governance

This removes all knowledge, tasks, and configuration. Make sure to back up anything you want to keep first.