Getting Started with PiDeck: A Complete Guide to the Local AI Coding Workbench

If you're already writing code with Claude Code, Cursor, or other AI coding CLI tools, you've surely run into these pain points: switching projects, managing sessions, and reviewing history all depend on command-line operations. The AI conversations in each terminal window are isolated from one another, and once you close a window, last week's solution is gone for good. The tutorial series Getting Started with PiDeck by Bilibili creator Cao Ayu systematically introduces how PiDeck, an open-source desktop workbench, solves these problems. This article distills its six episodes into a complete getting-started guide.

Before diving in, it's worth understanding the ecosystem these tools live in. Over the past two years, command-line AI coding assistants have risen rapidly. Claude Code from Anthropic lets developers drive large models with natural language directly in the terminal to write, debug, and refactor code. Cursor and Windsurf represent another path, deeply integrating AI into a VS Code–like graphical editor. What these tools share is that they upgrade the large language model (LLM) from a "Q&A box" into an Agent capable of reading project files, executing commands, and modifying code. However, while CLI tools are lightweight and scriptable, they inherently lack session persistence and multi-project management—each terminal window is a separate process, making historical conversations hard to search. PiDeck emerged precisely to fill this gap. It doesn't reinvent the wheel; instead, it wraps existing CLIs in a unified graphical management layer.

What Is PiDeck: A Graphical Shell for CLIs

PiDeck is essentially a desktop workbench specifically designed to manage your AI Agent sessions. In the plainest terms, it wraps an Electron shell around command-line tools, but users don't need to worry about what's happening underneath at all—they only need to remember one core concept: PiDeck is a unified place to manage AI conversations across all your projects.

Electron here deserves a bit more explanation. It's the technical foundation behind mainstream desktop software like VS Code, Slack, and Discord. Its core idea is to render the interface with Chromium and handle system-level logic with Node.js, enabling developers to build cross-platform desktop apps using web technologies (HTML/CSS/JavaScript). This explains why PiDeck strongly depends on a Node.js environment, and why it can offer three installers at once: Windows EXE, Mac DMG, and Linux AppImage. For PiDeck, the Electron shell handles rendering the project list, conversation area, file tree, and other graphical elements, while the actual interaction with the large model is still done by the underlying, encapsulated CLI process.

Its interface layout is very clear—the project list on the left, the conversation area in the center, and the file tree and session history on the right. The most crucial design is complete project isolation: the context of Project A won't contaminate Project B. You can freely switch between multiple projects, and the AI in each one remembers where you left off last time.

The core mental model is also simple: one Agent Tab equals one CLI process. On top of retaining all the capabilities of the raw command line, PiDeck additionally provides multi-project workspaces, session visualization, Git integration, a built-in terminal, a graphical config editor, and a built-in curated Chinese prompt library (reportedly containing over 4,000 prompts, importable with one click).

Who Should Use PiDeck

According to the tutorial, PiDeck is primarily aimed at four types of users: first, developers already using CLIs who find terminal management too cumbersome; second, people migrating from Cursor or Windsurf who want a lighter, more flexible solution; third, team development scenarios where multi-project switching is the norm; and fourth, newcomers still on the fence about AI coding tools. It makes a good starting point because it's free, open-source, and free of vendor lock-in.

Installing PiDeck and Environment Detection: Order Matters

Installing PiDeck follows an easily overlooked yet critical principle—get the underlying CLI working first, then add projects and launch the Agent. The correct installation order has three steps:

1. Install Node.js version 20 or higher (from the Chinese download page at nodejs.org);
2. Install the corresponding AI command-line tool;
3. Then install and open PiDeck to complete environment detection.

Installers can be downloaded from GitHub Releases: EXE for Windows, DMG for Mac, AppImage for Linux. Before installing, it's recommended to run node --version and the corresponding CLI version command in the terminal to confirm the foundation is ready.

Details of Environment Detection

When you first open PiDeck, it automatically runs environment detection—this is the most critical step. The program searches for CLI executables in the system path and common paths. If it can't detect them, it provides installation guidance. For users of version managers like NVM, PNPM, or similar tools, you often need to manually specify the path to the executable. The reason this tends to cause problems is that tools like NVM (Node Version Manager) install Node.js and its global packages in hidden paths under the user directory rather than the system default directory, so PiDeck's automatic scan can't find them—this is also a common pitfall for many cross-language developers when configuring terminal tools.

Under "Settings → Developer Settings," you can customize paths, set detection flags, and trigger re-detection. After entering the path, click "Validate and Use"; when you see a green CLI status, the configuration succeeded. Before finishing this episode, make sure all four things are complete: Node.js installed, CLI installed, PiDeck opened, and environment detection passed.

Configuring Models and Authentication: Don't Confuse the Two Methods

Getting the environment working isn't enough—you also need to tell PiDeck which model provider to use and how to enter the API Key. The tutorial specifically emphasizes configuring the model before opening a project—because once the Agent launches, it needs to be able to converse immediately. If the model isn't configured, opening a project still won't let you send valid requests.

PiDeck offers two configuration methods; do not confuse them:

• Models (Models Page): Suitable for custom providers, relay services, or OpenAI-compatible interfaces. You need to fill in the Base URL, API type, and API Key, then fetch or manually add the model list.
• Auth (Authentication Page): For officially direct-connected providers like DeepSeek. In most cases, you only need to enter the API Key—no need to assemble the Base URL yourself.

This distinction reflects the two typical forms of the current AI model integration ecosystem. The "OpenAI-compatible interface" has become the de facto standard—services including DeepSeek, Tongyi, and many open-source model deployment tools mostly provide Base URLs and call formats that conform to the OpenAI API specification, so clients only need to switch the URL and Key to connect to different models. So-called "relay services" are proxy layers built by third parties on top of official APIs, typically used for unified billing, bypassing regional restrictions, or aggregating multiple model providers. Understanding this makes it clear why official providers use Auth (direct connection, no URL assembly needed) while relays and custom providers use Models (requiring you to manually enter the Base URL)—the two correspond to two different network paths: direct connection and proxy.

Just remember the division of labor: prioritize Auth for official providers, and use Models for relay or custom interfaces. When configuring on the Models page, you can first click "Configuration Guide," and after filling in the information, be sure to click "Save" for it to take effect.

It's worth mentioning that after the configuration is saved, the entry point for switching models is at the bottom of the conversation input box (not the top). Click the model name to switch the model and thinking level. This is the spot newcomers are most likely to look for in the wrong place.

Adding Projects and Your First Conversation

Once the environment and models are ready, you can add local projects. Click the plus sign at the top left, select a local project directory, and the project will appear in the left list.

Note that adding a directory does not automatically start a conversation—you still need to manually launch the Agent. There are several ways to launch it: click the plus sign in the project row in the sidebar, click the "Launch Agent" button on the central blank page, or start/restart it in the new session area at the top right. Only after a successful launch and entering the conversation interface can you select a model and send messages.

Stringing the first four episodes together, the complete basic loop is: install Node → install CLI → install PiDeck → environment detection → configure Models/Auth and save → add project → launch Agent → select model at the bottom → send message. Once you confirm there's a local project on the left, the Agent has launched, you can switch models at the bottom, and you receive replies, the basic loop is complete.

Advanced Conversation: Making Questions More Effective

Sending messages is just the beginning. Episode five covers a more robust way of asking questions, with the core principle being start with a specific problem—don't just say "help me check the code," but clearly state the goal, file, and constraints, like "see what's wrong with a certain file" or "add a dark mode toggle to the login page."

Several practical features are worth mastering:

• File references: Type @ in the input box to select project files. The file content goes directly into the context, no copy-paste needed.
• Slash commands: Typing / pops up a list of available commands. The commonly used compact compresses the context to free up tokens, and there are session-related commands to explore on your own.
• Shell commands: Type ! followed by a command (like !git status) to execute it in the current project directory, with output returned to the conversation area—ideal for quickly checking status, viewing diffs, or running tests.

The "Context" that appears here is a key concept for understanding AI coding tools. Every time a large model generates a reply, it takes the previous conversation and the content of referenced files together as input. This total input is limited by the "context window," measured in Tokens (roughly 0.75 English words each, or fewer characters for Chinese). As the conversation grows longer and more files are referenced, Tokens gradually approach the limit, causing the model to "forget" earlier information or respond more slowly. This is precisely the point of the compact slash command—it compresses lengthy history into a summary to free up Token space. Similarly, the tutorial's advice to "start a new session when switching topics" is essentially aimed at preventing irrelevant context from occupying precious window capacity and interfering with the model's judgment.

Replies support Markdown and streaming display, and the activity trail below shows which files the AI read, which commands it ran, and which code it changed. The recommended workflow is: confirm the model and thinking level at the bottom → use @ for relevant files and state a specific request → review the activity trail and results → verify changes with !git diff → start a new session when switching topics to avoid context contamination.

PiDeck Advanced Features: Unleashing Full Potential

If you only use the conversation feature, the tutorial estimates you're using only about 30% of PiDeck's capabilities. The final episode quickly covers several advanced features:

• Multi-project workspace: Add multiple local projects on the left and switch anytime, with each project's context independent.
• Git version control: View branches, changes, and commit records on the right.
• Built-in terminal: At the bottom, choose PowerShell, cmd, Git Bash, etc. Along with the ! commands in conversations, they all execute in the current project directory.
• Session history: One of the most intuitive improvements over the command line—browse history by project, restore context with one click, and export records for archiving.
• Prompt store: A built-in curated Chinese prompt collection, supporting category search and one-click import.

Summary

Compared to raw CLIs, PiDeck retains all native capabilities while adding multi-project graphical management, session history visualization, Git and terminal panels, and a graphical config editor. For developers who switch between multiple projects daily and are tormented by terminal session management, it's an efficiency tool worth trying. Combined with its free, open-source, and vendor-lock-in-free characteristics, it also makes an excellent starting point for newcomers entering AI coding workflows. Interested readers can visit its GitHub project page to learn more.

Key Takeaways