stashbase

Name: stashbase
Author: liliu-z

Warning

Turn local files into searchable context for AI agents.

363stars

23forks

TypeScript

Installation

# Add to your Claude Code skills
git clone https://github.com/liliu-z/stashbase

Getting Started

Guides for using ai agents skills like stashbase.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportWarning

Last scanned: 7/30/2026

{
  "issues": [
    {
      "type": "npm-audit",
      "message": "@electron/asar: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "@electron/universal: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "app-builder-lib: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "brace-expansion: brace-expansion: DoS via unbounded expansion length causing an out-of-memory process crash",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "dir-compare: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "dmg-builder: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "ejs: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "electron-builder: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "electron-builder-squirrel-windows: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "electron-winstaller: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "filelist: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "glob: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "jake: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "minimatch: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "rimraf: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "temp: Vulnerability found",
      "severity": "high"
    }
  ],
  "status": "WARNING",
  "scannedAt": "2026-07-30T06:27:15.682Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

README.md

Frequently Asked Questions

What is stashbase?

stashbase is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by liliu-z. Turn local files into searchable context for AI agents. It has 363 GitHub stars.

Is stashbase safe to use?

stashbase returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.

How do I install stashbase?

Clone the repository with "git clone https://github.com/liliu-z/stashbase" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is stashbase written in?

stashbase is primarily written in TypeScript. It is open-source under liliu-z on GitHub, so you can review or fork the full source.

Are there alternatives to stashbase?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh stashbase against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

240,740

tmux-claude-session-manager awesome-foundation-model-leaderboards

StashBase

Turn local files into Agent-ready context.

Much of your best context already lives in local files: notes, papers, contracts, project data, scanned documents, and recordings. Open a folder in StashBase and work with that material in place:

📂 Work in place: browse, read, and edit supported files without moving them into a proprietary workspace.
🔎 Prepare and search: extract difficult formats, search exact text immediately, and optionally add meaning-based retrieval with AI Index.
🤖 Use with Agents: run Claude Code or Codex in the built-in Chat, or share the same authorized library with other MCP clients.

Your folders remain the source of truth; StashBase adds a search index that can be rebuilt from them.

The core idea:

Local files -> prepared evidence -> retrieval -> Agents

🚀 Demo

Open this repo in StashBase and ask the built-in Agent: How is this project designed?

StashBase demo: opening local design docs and asking the Agent about architecture and product direction

💡 Try It

StashBase's primary platforms are macOS 12+ (Apple Silicon) and Windows 10+ (x64). A community-supported Linux build is also available for x86_64 Debian 12+ / Ubuntu 22.04+.

macOS

Apple Silicon Macs running macOS 12 or later can install with Homebrew:

brew install --cask liliu-z/stashbase/stashbase

Or download the StashBase-*-mac-arm64.dmg from Releases, drag the app to Applications, and open it there. Published macOS artifacts are signed with Apple Developer ID and notarized by Apple.

Windows

Download the latest StashBase-*-win-x64.exe installer from Releases
Run the installer
If Windows SmartScreen appears:
- Windows SmartScreen is a security feature that warns about files from the internet. Since you've confirmed the installer came from the official GitHub Releases page, it's safe to proceed
- Click More info → Run anyway
Follow the installer prompts to complete installation

To update: Quit StashBase, then run the newer installer over the existing installation.

To uninstall: Open Settings → Apps, then select StashBase under Installed apps (Windows 11) or Apps & features (Windows 10).

Linux

For Debian 12+ or Ubuntu 22.04+ on x86_64, download the latest StashBase-*-linux-amd64.deb asset from Releases, then install it with apt so any required system packages are resolved:

sudo apt install ./StashBase-*-linux-amd64.deb

Run the same command with a newer package to update. To remove StashBase, run sudo apt remove stashbase.

For a portable build, download StashBase-*-linux-*.AppImage, make it executable with chmod +x, and run it directly.

First Launch

The first window opens with no folder selected and one reusable blank Chat.

Enable AI Index: Sign in to StashBase for free monthly AI Index usage, or use your own OpenAI/OpenRouter key. To continue without it, choose Skip AI Index for now; exact text search and local file work remain available.
Ask how StashBase works: In the Chat that is already open, ask “How do I use StashBase?” It starts against the whole Library, including Start Here. StashBase uses a supported system Claude Code or Codex runtime when available; if it is missing, installation waits for Install and continue. Agent provider login is separate from StashBase sign-in and AI Index configuration.
Open source files when you need them: On a brand-new empty default folder home, StashBase adds 👋 Start Here to the Library without opening it automatically. Open it from the titlebar's Library menu, or use Add Folder… to work with one of your own local folders. Selecting a source brings it alongside the same conversation.

StashBase processes only folders in its Library. Apart from the bundled Start Here introduction, folders join only when you explicitly add or open them. You can remove a folder at any time; StashBase clears its app-owned state but never deletes your files from disk.

Transcription and external MCP access can be configured later when you need them. Neither is required to begin browsing local files.

Updating and Uninstalling

Updates: Quit StashBase and run the newer installer. Your library and settings are preserved
Uninstalls: On macOS, remove StashBase from Applications; on Windows or Linux, follow the platform-specific removal steps above. Your local files are never deleted

Troubleshooting Installation

Installer won't start on Windows

Make sure the file extension is .exe (not .msi or other formats)
Try running the installer as Administrator (right-click → Run as administrator)
If antivirus software blocks it, temporarily disable it and try again (it's safe to do so from official releases)

macOS blocks or rejects the downloaded app

Delete that copy and download the current DMG again from the official Releases page
Do not bypass Gatekeeper for an artifact that still reports a signing or malware-verification problem; report the StashBase version and macOS version in the Discord community

App won't launch after installation

Try restarting your computer
Uninstall and reinstall the latest version
Check the Discord community for help

Out of disk space errors

Your library index needs space proportional to your files. Add more disk space or remove large files
Remove the folder from the Library to clear its StashBase-owned index and derived data. Your source files are never deleted

Can't find installed app

On Windows: Press the Windows key and search for "StashBase"
On macOS: Open Finder → Applications → look for StashBase
On Linux: Run stashbase from terminal or find it in your applications menu

Document Workbench

StashBase works directly with ordinary local folders. The Files sidebar, persistent tabs, Quick Open, and format-specific viewers keep source work in the same workspace as Chat.

Use File → New Window or Cmd/Ctrl+Shift+N to keep different folders and tools side by side. Window close follows VS Code's platform shortcuts; Cmd/Ctrl+W continues to close the active document tab.

Use Cmd/Ctrl+O to open a source file in the active folder. The Command Palette opens with Cmd/Ctrl+Shift+P or F1 (or by typing > in Quick Open) and exposes safe application actions with their existing safeguards.

Search and Preparation

The local RAG layer has two core jobs: prepare files and index their contents.

Prepare

Some formats need preparation before their contents can be searched. StashBase keeps the original files in place and creates derived text only where needed for search and Agent access.

Format	Visible source	Indexed text
Markdown	The Markdown file	Source text
HTML	The HTML file	Clean text extracted from the HTML
JSON	The JSON file	Source-preserving tree and exact source text
PDF	The original PDF	Derived Markdown
DOCX	The original DOCX	Derived HTML
Images	The original image	OCR text
Audio and video	The original media	Audio track transcribed locally to timestamped Markdown

For PDF, DOCX, audio, and video, Agents read the derived text while the original remains the visible source file. Audio and video play directly when supported; otherwise, StashBase creates a compatible local audio preview. Large files dragged into the app stream to disk instead of being held entirely in memory. See Architecture and Preparation for the product and system contracts.

Preview, Workbench editing, retrieval text, Agent reads, and file writes are separate capabilities. See the canonical Format Capability Matrix for the current per-format boundary.

Audio and video transcription is optional. Download a local speech model from Settings → Transcription when you need it. Small (465 MiB) is the default; Tiny (74 MiB) and Base (141 MiB) are lighter choices. Transcription runs on your machine with no transcription API cost.

AI Index

Sign in to StashBase for free monthly AI Index usage, or configure your own OpenAI/OpenRouter key in Settings → AI Index. An OpenAI restricted key needs access only to embeddings with text-embedding-3-small; model-list access is not required. Exact search needs neither option.

StashBase builds its AI Index and exact text search over:

Markdown, HTML, and raw JSON text
PDF-derived Markdown
DOCX-derived HTML
OCR text from images
timestamped transcripts from audio and video

Search results point back to the user-visible source file, not hidden app data.

Hosted indexing and meaning-based queries share one monthly token allowance. The avatar menu shows the remaining percentage and reset date. If the hosted allowance runs out, Exact search and all local file workflows keep working.

Background preparation is intentionally quiet. Browsing a folder should feel like browsing files, not watching an indexing job. If preparation fails, StashBase shows a lightwe