Docs

Installation

Agenties ships as a native desktop application built with Tauri v2. There is no browser extension, no cloud IDE, and no Docker container — just a single installable binary that runs locally on your machine and talks to Claude Code via its MCP server. Install it in seconds via npm.

Requirements

Required
Node.js 20+ and npm
Required for the npm package and the internal sidecar. Verify with node --version.
Required
Git
Required — agents use git for version control. Verify with git --version.
Required
Claude Code CLI
Agenties spawns Claude Code processes. Install with npm install -g @anthropic-ai/claude-code, then run claude login to authenticate.
Required
Windows 10/11, macOS 12+, or Linux (x64)
Agenties builds are available for all three platforms.
Optional
Obsidian
Optional. Agenties exports human-readable session summaries, decisions, and research notes to an Obsidian vault. Operational project state always lives in .agenties/ — Obsidian is a readable mirror, not the source of truth.
Optional
NotebookLM
Optional alternative session memory provider. Connect via Settings → Memory. Same caveat as Obsidian: .agenties/ remains the operational source of truth.
Optional
Python 3.10+ (voice features)
Required only if you want push-to-talk (STT) or text-to-speech (TTS). Install edge-tts and faster-whisper into a virtual env at ~/.notebooklm-venv — Agenties detects it automatically. Voice is fully optional; the rest of Agenties works without Python.
Optional
Python 3.10+ (Graphify)
Required only if you enable the Graphify code knowledge graph feature. Agenties auto-installs the graphify binary into .agenties/tools/graphify-venv/ — you just need Python 3.10+ available on your PATH. No manual pip install needed.

Step 1: Install and authenticate Claude Code

If you don't already have Claude Code installed, run the following in your terminal:

bash
npm install -g @anthropic-ai/claude-code

Then authenticate with your Anthropic account:

bash
claude login

Verify the installation with:

bash
claude --version
Note:Agenties uses the MCP (Model Context Protocol) server built into Claude Code. Your Claude Code session IS the auth — no API keys or extra credentials needed. Make sure you're on Claude Code version 1.2.0 or later, which includes the full MCP tool set Agenties requires.

Step 2: Install Agenties

Install Agenties globally via npm and launch it:

bash
npm install -g agenties
agenties

That's it. No API key. No separate auth step. Your active Claude Code session is all you need.

Tip:Agenties checks for updates automatically. When a new version is available, run npm install -g agenties again to upgrade.

Step 3: First launch

When you launch Agenties for the first time, the setup wizard walks you through four steps:

1
Detect Claude Code
Agenties scans your PATH for the claude binary and tests that it can spawn a process. If detection fails, you can enter the path manually in Settings > General.
2
Connect your account
Sign in with your Agenties account (the same account used on agenties.app). This links your subscription and enables multi-PC sync through the Agenties cloud backend.
3
Configure your vault (optional)
Optionally, enter the path to your Obsidian vault folder. Agenties will create a project subfolder and use it for human-readable knowledge exports — session summaries, decisions, and research notes. Operational project state is always stored in .agenties/ regardless of this setting. You can skip this and configure it later in Settings → Memory.
4
Create your first project
Pick a folder on disk that contains (or will contain) your codebase. Agenties creates a .agenties/ directory inside it to store local state.
Tip:You can re-run the setup wizard at any time from Settings → General → Re-run setup.

Project directory structure

Agenties creates the following files inside your project folder on first use:

Project structure
.agenties/
├── config.json          # heartbeats, tool permissions, sync settings
├── agents.json          # active agent registry
├── team.json            # team roster with XP and stats
├── issues.json          # issue tracker
├── goals.json           # persistent project goals
├── skills.json          # registered skills
├── audit.jsonl          # append-only event log (never synced)
├── continuity/
│   ├── journal.md       # chronological task log
│   └── index.md         # pinned decisions and thematic history
├── graphify/            # Graphify code knowledge graph output (when enabled)
├── sessions/            # per-session agent reports
├── shared/
│   ├── state.json       # current phase, objective, active agents, decisions
│   ├── mailbox.jsonl    # inter-agent message bus (never synced)
│   └── orchestrator-guide.md
├── team/                # per-member state files
└── tools/
    └── graphify-venv/   # Graphify Python env, auto-managed by Agenties

All files are local by default — .agenties/ is always the operational source of truth. When sync is enabled, config.json, team.json, issues.json, and goals.json are optionally mirrored to the Agenties cloud backend. The shared/, continuity/, sessions/, and audit.jsonl are never synced — they hold local operational state that is meaningful only to the running instance.

Warning:State files in .agenties/ are forward-compatible — new versions can always read files created by older versions. Never manually edit these JSON files while Agenties is running, as your changes may be overwritten by a sync flush.