convez.ai
Agente
JeltzProstetnic

agent-fleet

JeltzProstetnic/agent-fleet

Ver no GitHub
BomPluginScore · de 0 a 100

Configuration management system for Claude Code. Session memory, 5-layer knowledge architecture, multi-machine sync, cross-project coordination. Works on Linux, macOS, and WSL.

Instalação

$npx convez-ai JeltzProstetnic/agent-fleet

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 1 dia
Versão
v1.0
Issues abertas
4
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

Agent Fleet

A persistent, multi-project, multi-machine AI agent that manages your development infrastructure through conversation.

Install, Launch, Talk

git clone https://github.com/JeltzProstetnic/agent-fleet ~/agent-fleet
cd ~/agent-fleet && bash setup.sh
afleet

The agent introduces itself and asks how you work -- your projects, your communication style, your tools. No forms. No config files. Just a conversation. Everything after this point is "tell the agent what you need."

Want your own copy? On GitHub, click "Use this template" to create a private repo, then clone that instead. Setup detects the template origin and reconfigures remotes automatically.

For a more detailed walkthrough, see the Getting Started Guide.


Quick Start

Prerequisites

  • Linux, macOS, or Windows with WSL
  • git, curl, and Python 3 installed
  • Node.js 18+ (optional — setup installs it via NVM if missing)

Windows users: Claude Code runs inside WSL. If you haven't set it up: PowerShell as Admin, wsl --install, restart, open the Ubuntu app. Everything below happens in that terminal.

Five minutes to a working agent

1. Clone

git clone https://github.com/JeltzProstetnic/agent-fleet ~/agent-fleet
cd ~/agent-fleet
bash setup.sh

Want a private copy? On GitHub, click "Use this template" -> "Create a new repository" (set it to Private), then clone your copy instead. Do NOT fork -- GitHub forks are public by default. Setup detects whether origin points to the template or your own repo and configures remotes accordingly.

The script detects your OS, installs dependencies, creates symlinks, sets up session hooks, and installs the afleet launcher. If origin still points to the template repo, setup automatically renames it to upstream (for pulling updates) and clears origin -- your own repo gets set as origin during first-run setup.

2. Set up credentials (optional)

Copy setup/secrets/vault.json.example to setup/secrets/vault.json, add your tokens, then encrypt:

bash setup/secrets/vault-manage.sh encrypt

Or configure MCP servers manually in ~/.mcp.json. Or skip this entirely and tell the agent to set up integrations later.

3. Launch and talk

afleet

afleet is the fleet launcher -- it syncs your repos, detects the current project, and starts Claude Code in the right directory. If no project is detected from the current directory, it shows an interactive project picker.

On first launch, the agent detects a .setup-pending marker and starts onboarding -- a conversation about who you are, what you work on, and how you want the agent to behave. It writes everything to the right config files. You can change any of it later by just telling the agent.

Warning: Do NOT run /init. Claude Code's splash screen recommends /init to create a CLAUDE.md. In an agent-fleet deployment, CLAUDE.md is already configured and managed. Running /init will overwrite it with a generic stub, breaking your entire setup. If this happens, restore with git checkout -- CLAUDE.md. A startup hook (init-guard) detects this and warns, but prevention is better than recovery.

Every session after the first is automatic: pull latest config, load project knowledge, restore state, check for cross-project tasks.

Which Claude model did you get? setup.sh installs whatever Claude Code is current on npm, which (as of June 2026) bundles Opus 4.8 by default (CC 2.1.153+). On CC 2.1.170+ you can also select Fable 5 (alias fable), Anthropic's preview flagship — selectable, never the default. To pin a specific Claude Code / model version at install time, set CLAUDE_CODE_VERSION=2.1.110 bash setup.sh (gives you Opus 4.6 + Fast Mode). To check, switch post-install, or read the trade-offs: see docs/model-version-guide.md.


The Fleet Launcher

afleet replaces bare claude as the entry point. It adds pre-launch sync, project detection, and a terminal-based project picker -- all without consuming LLM tokens.

afleet                    # Auto-detect project from CWD, or show picker
afleet <project-name>     # Open a specific project by name
afleet --pick             # Interactive project picker (priority-grouped)
afleet --pick --all       # Include paused/dormant (P4-P5) projects
afleet --list             # Non-interactive project list

The picker displays projects grouped by priority tier (P1 Critical, P2 Active, P3 Ongoing), with task counts, P1 task names, and disk sizes pulled from a dashboard cache. Type a number or letter to select, Enter for the CWD project, q to quit.

Before launching, afleet automatically:

  • Pulls the target project and config repo from git
  • Background-pulls all other registered repos (prevents stale cross-project state)
  • On SteamOS: detects OS version changes and re-provisions system packages if wiped

Cross-project navigation (opening projects in new terminal tabs):

afleet-nav tab <project>         # Open in new terminal tab (keep current session)
afleet-nav switch <project>      # Open in new tab, close current session
afleet-nav notify <project> msg  # Drop a task in the cross-project inbox
afleet-nav info <project>        # Show project info from registry

Platform-aware: uses Windows Terminal (wt.exe) on WSL, Konsole (qdbus) on KDE, tmux new-window in tmux, and prints manual instructions as fallback.


Quick Commands

lsd     project dashboard (in-session, reads dashboard cache)
cls     clean shutdown (then /clear or exit)
lrn     self-audit: rules, knowledge gaps, improvements
sub     delegate a task to a subagent
afk     AFK mode: dangerous commands route to Telegram for approval

Type any of these as your entire message. cls (or end) runs the full shutdown protocol -- save state, archive session, commit, push -- so you never lose work. lsd shows a priority-grouped dashboard with task counts and disk sizes. lrn launches parallel subagents to audit the session for rule violations, uncaptured knowledge, and improvement opportunities. sub <task> delegates work to a background subagent. afk enables remote approval of dangerous commands via Telegram.

These are shortcuts, not the interface. The interface is conversation.


Common Things You Can Say

You sayWhat happens
"Set up this project"Creates config, adds to registry, initializes session tracking
"Switch to my other project"Archives current state, opens a new tab in the target project
"Add GitHub integration"Configures the MCP server, walks you through credentials
"Show me the backlog"Reads and displays prioritized tasks for the current project
"Pass this task to the infra project"Drops it in the cross-project inbox -- picked up at next session start
"What happened last session?"Reads session history and summarizes
"Deploy my config to the other machine"Commits, pushes; the other machine auto-pulls on next launch
"Always use bun instead of npm in this project"Adds a permanent rule to the project config
"Something's wrong with the GitHub MCP server"Diagnoses the issue -- checks config, tokens, permissions, whitelist
"Prepare for shutdown"Runs the full shutdown checklist without being asked twice

The agent knows about all your projects (via the registry), all your machines (via machine files), and all cross-project state (via the inbox and strategy files). You don't need to memorize paths or commands.


First-Run Onboarding

On first launch after setup, the agent starts a conversation:

  • Who you are -- name, role, what you work on
  • Communication style -- concise or verbose, formal or casual, humor preferences
  • Personas -- optionally define multiple personalities (e.g., a focused workhorse by default, a warmer voice when you're frustrated). Each has a name, traits, and a natural-language activation rule
  • Integrations -- which external services to connect (GitHub, Gmail, Jira, etc.)
  • Projects -- what you're working on, where the repos live

The agent writes everything to the correct config files. Nothing is permanent -- tell the agent to change anything, anytime.


How It Works

You don't need to understand this to use it. But if you're curious:

Knowledge Layers

graph TD
    A["<b>Layer 1: Global Prompt</b><br/>The dispatcher -- tells the agent what to load<br/><i>Always loaded</i>"] --> B
    B["<b>Layer 2: Foundation</b><br/>Session rules, your identity, protocols<br/><i>Always loaded</i>"] --> C
    C["<b>Layer 3: Domains</b><br/>Coding rules, infra rules, writing rules<br/><i>Only if the project needs them</i>"] --> D
    D["<b>Layer 4: References</b><br/>Tool guides, troubleshooting<br/><i>Only when needed</i>"] --> E
    E["<b>Layer 5: Project Rules</b><br/>Project-specific instructions + session state<br/><i>Per project</i>"]

    style A fill:#2d6a4f,stroke:#1b4332,color:#fff
    style B fill:#40916c,stroke:#2d6a4f,color:#fff
    style C fill:#52b788,stroke:#40916c,color:#fff
    style D fill:#74c69d,stroke:#52b788,color:#000
    style E fill:#95d5b2,stroke:#74c69d,color:#000

The agent doesn't load everything at once. A coding project loads TDD rules. An infrastructure project loads server protocols. This keeps the agent fast, focused, and leaves room in the context window for actual work.

Session Persistence

The agent maintains session-context.md in every project directory. It tracks what's in progress, what's done, and how to resume if the session terminates unexpectedly.

ProtectionHow
Continuous archivalSessionEnd hooks auto-rotate state to history -- even on /clear, crashes, or unexpected exits
Unclean shutdown detectionSessionStart hooks detect when the previous session didn't shut down properly and warn the agent to review what was lost
Config health checkSessionStart hooks validate symlinks, auto-pull if behind remote, clean stale permissions, inject session metadata
Cross-project commitSession files in the current project get committed automatically at session end
Live context meterStatus line shows model, context usage %, and kilotokens -- color-coded so you know when to wrap up
Session lockPID-based lock prevents two sessions from working on the same project simultaneously

Session Hooks

Three hooks automate session lifecycle:

HookTypeWhat it does
config-check.shSessionStartSyncs config, validates symlinks, injects hostname/time/persona/inbox/context into the session
config-auto-sync.shSessionEndRotates session state, commits project + config, pushes to remote, collects mobile outbox
context-budget.shUserPromptSubmitInjects CONTEXT_BUDGET: NN% used every turn so the agent tracks its own resource usage

Session Flow

graph LR
    subgraph START ["Session Start"]
        S1[Pull latest config] --> S2[Load knowledge layers]
        S2 --> S3[Restore session state]
        S3 --> S4[Check inbox for tasks]
    end

    subgraph WORK ["During Work"]
        W1[You work normally] --> W2[Rules enforced automatically]
        W2 --> W3[State saved as you go]
    end

    subgraph STOP ["Session End"]
        E1[Save final state] --> E2[Sync config to git]
        E2 --> E3[Push to remote]
    end

    START --> WORK --> STOP
    STOP -- "any computer, any time" --> START

    style START fill:#1a535c,stroke:#0b3d45,color:#fff
    style WORK fill:#4ecdc4,stroke:#1a535c,color:#000
    style STOP fill:#ff6b6b,stroke:#c94040,color:#fff

Cross-Project Coordination

Projects communicate through cross-project/inbox.md. When one project needs another to act, the agent drops a task in the inbox. The target project picks it up automatically at next startup.

Direct file writes between projects are forbidden -- the inbox keeps projects decoupled and prevents silent data corruption.

Multi-Persona System

Define multiple named personalities with automatic context-based switching:

  • Name -- displayed as a bold prefix on responses (e.g., **Atlas:**)
  • Traits -- comma-separated style descriptors (efficient, dry-humor, warm, etc.)
  • Activation rule -- natural language (e.g., "when user is frustrated", "when discussing architecture")
  • Style -- free-text description of communication approach

The default persona activates at session start. Others switch in when the agent detects a matching condition. You can force a switch by saying "switch to [Name]."

Personas are defined in global/foundation/personas.md. Machine-specific overrides go in that machine's config file. Personal overrides go in personas.local.md (gitignored -- survives upgrades). The setup onboarding offers to configure them conversationally.

Grind Progress Indicator (GPI)

Track long-running operations in the terminal status line:

gpi start  <id> <label>     # Start tracking an operation
gpi update <id> --pct 45    # Update progress
gpi done   <id>             # Mark complete
gpi status                  # Show all active operations

Operations show as progress bars in the Claude Code status line. When an operation completes, the context-budget.sh hook notifies the agent on the next turn.


Mobile Access

Access your agent fleet from a phone or tablet through a lightweight, read-only repo:

# On any full machine:
bash sync.sh mobile-deploy

This creates ~/agent-fleet-mobile/ with:

  • Read-only snapshots of your projects, dashboard, and registry
  • An outbox (inbox/outbox.md) -- the only writable file
  • A minimal CLAUDE.md -- no startup checklist, no hooks, instant-on

Post tasks from mobile and they flow back automatically:

Mobile -> outbox.md -> sync.sh mobile-collect -> cross-project inbox -> target project

The mobile-collect step runs automatically at session end on any full machine. Or run it manually: bash sync.sh mobile-collect.

Mobile mode is intentionally limited. It reads, it captures tasks, and it answers questions. It can't edit config, run deployments, or modify project source. This prevents multi-device conflicts while giving you full visibility into your system from anywhere.


Adding a Second Machine

git clone YOUR_REPO_URL ~/agent-fleet
cd ~/agent-fleet && bash setup.sh

Same two commands. The agent detects the new machine, creates a machine-specific config file, and everything syncs from there. Or tell the agent "help me set up my other machine" and it walks you through it.

graph LR
    A["Computer A<br/><i>session ends</i>"] -- "git push" --> GH["GitHub"]
    GH -- "git pull" --> B["Computer B<br/><i>session starts</i>"]

    style A fill:#264653,stroke:#1d3557,color:#fff
    style GH fill:#e9c46a,stroke:#f4a261,color:#000
    style B fill:#2a9d8f,stroke:#264653,color:#fff

No computer is special. Each machine gets its own file in global/machines/. Conflicts are rare because each machine writes to its own config and session-context is per-session.

Syncs via gitStays local
Rules, knowledge, session historyAPI tokens (~/.mcp.json)
Project configs, backlogsOAuth credentials
Cross-project inboxMachine-specific tool paths

Upgrading

When the template gets new features, pull them into your copy:

bash setup/scripts/upgrade.sh

One command. It creates a rollback tag, pulls latest changes (fast-forward only), and deploys to live locations. Your personas, machine files, hostname mappings, and secrets are untouched -- they live in gitignored *.local.* files that the upgrade never touches.

If something breaks after an upgrade, roll back instantly:

bash setup/scripts/upgrade.sh --rollback

Dry run (see what would change without changing anything):

bash setup/scripts/upgrade.sh --dry-run

What's in the Box

Directory Structure

agent-fleet/
|
|-- setup.sh                       Run once -- sets everything up
|-- sync.sh                        Config sync (automated by hooks)
|-- registry.md                    All your projects (created at setup)
|-- .agent-fleet-version           Version tracking for upgrades
|-- CHANGELOG.md                   Release notes
|-- CONTRIBUTING.md                Contribution guidelines
|-- template-sync-manifest.md      Hash manifest for template drift detection
|
|-- sync-lib/
|   |-- common.sh                  Shared helpers (hostname, project path, manifest parsing)
|   `-- check.sh                   Template drift and personal data leak checks
|
|-- global/
|   |-- CLAUDE.md                  The main prompt (the "dispatcher")
|   |-- foundation/                Session protocol, identity, personas
|   |-- domains/                   Topic rules (coding, infra, publishing)
|   |-- reference/                 Tool guides, troubleshooting
|   |-- knowledge/                 Operational tips and workarounds
|   |-- machines/                  Per-computer configuration
|   `-- hooks/                     SessionStart/End/UserPromptSubmit automation
|       `-- checks/                Modular SessionStart check modules (01-07)
|
|-- setup/
|   |-- install.sh                 Main installer (called by setup.sh)
|   |-- install-base.sh            Phase 1: system deps, Node.js
|   |-- configure-claude.sh        Phase 2: MCP, launchers, hooks, afleet
|   |-- lib.sh                     Shared utilities (multi-distro detection)
|   |-- migrations/                Version migration scripts (v0.3, etc.)
|   |-- config/                    Template configs (settings, statusline, aliases, etc.)
|   |-- scripts/                   Operational scripts (see below)
|   |-- secrets/                   Vault scaffold (vault.json.example)
|   |-- icons/                     Priority badge icons for project folders
|   |-- vps/                       VPS bootstrap and web terminal setup
|   |-- projects/
|   |   `-- _example/rules/CLAUDE.md   Example project config
|   `-- tests/
|       |-- run.sh                 Test runner
|       `-- test-*.sh              73 test suites (~1,150 tests)
|
|-- docs/
|   |-- getting-started.md         Detailed setup and usage walkthrough
|   |-- security-one-pager.md      Security architecture reference
|   |-- dms-guide.md               Document management system guide
|   |-- hardening-plan.md          Security hardening plan
|   `-- placeholder-convention.md  Convention for placeholder text in templates
|
`-- cross-project/
    |-- inbox.md                   Task passing between projects
    |-- dashboard-cache.md         Machine-generated dashboard data (task counts, sizes)
    `-- *-strategy.md              Shared strategy files (infrastructure, visibility)

Key Scripts

setup/scripts/ contains operational scripts deployed by setup or run on demand:

ScriptWhat it does
afleet.shFleet launcher -- project detection, picker, pre-launch sync
afleet-nav.shCross-project navigation -- open tabs, switch projects, send notifications
rotate-session.shArchives session-context to history and session log
lsd-refresh.shGenerates dashboard cache from registry and backlogs
git-sync-check.shFetch, detect drift, fast-forward pull
filtered-push.shDual-remote push with path exclusion (personal data filtering)
gpi.shGrind Progress Indicator CLI (status line progress tracking)
fleet-issue.shPrivacy scrubber + dedup checker for filing GitHub issues
git-credential-mcpGit credential helper that reads GitHub PATs from .mcp.json
manage-pending.shPending file lifecycle engine (auto-promote, auto-clean)
inbox-archive.shArchives completed [x] items from cross-project inbox
session-lock.shPID-based session lock library
ask-passphrase.shMasked passphrase input (tkinter/zenity/kdialog/PowerShell)
clean-marketplace-plugins.shRemoves unwanted auto-installed Claude Code plugins
plugin-inventory.shScans installed plugins, reports token cost estimates
clean-permissions.shRemoves stale permission blocks from settings.local.json
project-icons.shGenerates priority badge icons for KDE/Windows project folders
infra-discover.shNetwork/environment discovery (interfaces, DNS, SSH, Docker, ports)
youtube-tabs.shSave/restore YouTube tabs across machines
update-checker.shClaude Code version checker (runs once per day at startup)
install-skill-collections.shInstall third-party skill packs
upgrade.shOne-command upgrade from upstream with rollback support
reprovision-steamos.shRe-install system packages after SteamOS update

Sync Tool

CommandWhat it does
bash sync.sh setupRun once per computer. Creates symlinks, installs hooks.
bash sync.sh deployPush config changes to live locations. Safe to repeat.
bash sync.sh collectPull changes from live locations back into the repo.
bash sync.sh statusHealth check -- shows what's linked, what's out of sync.
bash sync.sh checkAggregated drift/staleness check across all propagation chains.
bash sync.sh check-templatePre-publish validation (scans for personal data leaks).
bash sync.sh stampRefresh manifest hashes after template sync.
bash sync.sh mobile-deployCreate read-only mobile snapshot repo.
bash sync.sh mobile-collectMerge outbox tasks from mobile back to inbox.

You rarely need to run these manually. The session hooks handle sync automatically. But they're there if you want direct control.

MCP Servers

MCP servers let the agent interact with external services. All are optional -- configure during setup or tell the agent to add them later.

ServerWhat it doesNeeds credentials?
GitHubManage repos, issues, pull requestsYes (PAT)
Google WorkspaceGmail, Google Docs, Calendar, DriveYes (OAuth)
Twitter/XPost tweetsYes (API keys)
JiraIssues, sprints, ConfluenceYes (API token)
PostgreSQLDatabase queriesYes (connection URL)
LinkedInCreate postsYes (OAuth, manual setup)
SerenaSemantic code navigationNo
PlaywrightBrowser automation, screenshotsNo
Context7Library documentation lookupNo
DiagramMermaid diagram generation (PNG/SVG/PDF)No

Domains

Domains are topic-specific rule sets. Each project declares which ones it needs.

DomainWhat it teaches the agent
Software DevelopmentTDD, code review conventions
PublicationsMarkdown-to-PDF pipeline, content quality
EngagementCommunity interaction, social media etiquette
IT InfrastructureServer management, Docker, DNS, deployment

Add your own: copy global/domains/_template/, edit it, reference it from your project's CLAUDE.md.

Operational Knowledge

global/knowledge/ stores tool-specific tips, workarounds, and troubleshooting recipes. Unlike domains (broad rule sets declared per-project), knowledge files are narrow and actionable, growing organically from real debugging sessions. They load conditionally when the relevant tool or situation is encountered.

Test Suite

~1,150 tests across 73 suites, run via setup/tests/run.sh:

SuiteTestsCovers
harness14Test runner itself
rotate-session31Session archival, history rotation, template parsing
git-sync-check15Remote detection, fast-forward, divergence handling
sync24Deploy, collect, symlinks, hook copying
persona6Persona file parsing, switching logic
lsd-refresh9Dashboard cache generation, backlog scanning
statusline27Context meter, persona display, color coding
config-check77Symlink validation, stale session detection, permission cleanup, metadata injection
filtered-push16Dual-remote push, path exclusion, config parsing, safety checks
afleet21Fleet launcher, project detection, picker, SteamOS pre-flight
afleet-nav14Cross-project navigation, tab opening, notify, info
clean-marketplace-plugins10Plugin cleanup, dry-run, stale enabledPlugins
clean-pending7Pending file cleanup after resolution
clean-permissions8Permission block removal from settings.local.json
context-budget13Context budget injection, GPI completion notifications
fleet-issue34Privacy scrubber, dedup checker, issue formatter
git-credential-mcp8MCP credential extraction for git
gpi24Grind Progress Indicator CLI
inbox-archive11Archive completed inbox items
install-base7cc-mirror variant creation
install-setup16Setup edge cases, non-interactive mode, rollback
lrn-command22Self-audit quick command parsing
manage-pending20Pending file lifecycle engine
mobile28Mobile deploy/collect, outbox merge, idempotency
nvm-path12NVM path handling across platforms
plugin-inventory9Plugin audit and inventory
session-lock25PID-based session lock, stale lock cleanup
shell-rc8Shell RC patching (bashrc/zshrc)
template-drift9Template vs instance drift detection
template-smoke24End-to-end smoke test for clean template clone
upgrade9upgrade.sh, migration runner, version gating
youtube-tabs13Cross-machine YouTube tab persistence

TDD is enforced -- the agent writes tests before implementation code.

Skill Collections (optional)

Third-party skill packs extend Claude Code with domain-specific capabilities. Only short descriptions load at startup; full context loads on demand.

CollectionWhat it addsSource
getsentrySentry debugging skillsgetsentry/skills
obraSuperpowers skill packobra/superpowers
trailofbitsSecurity analysis, static analysis, binary analysistrailofbits/skills

Install all at once: bash setup/scripts/install-skill-collections.sh


Platform Support

Setup auto-detects your platform and installs dependencies accordingly.

PlatformPackage ManagerStatus
Ubuntu / DebianaptTested
WSL (Windows)apt (inside WSL)Tested
Fedora / RHELdnfTested
Arch / SteamOSpacmanTested
macOSHomebrewSupported

Windows: Claude Code runs inside WSL, not natively. See Quick Start for WSL setup.

SteamOS: The immutable filesystem requires temporary unlock during setup. The script handles this automatically and re-locks afterward. After OS updates, afleet detects version changes and auto-re-provisions wiped packages.

WSL tip: Always work in ~/, not /mnt/c/ -- Windows filesystem paths are 10-15x slower.


Security

Never commit secrets. API tokens, passwords, and credentials stay out of tracked files.

Token Handling -- Critical

Never paste tokens, API keys, or passwords into a Claude Code chat session. Session transcripts may be logged, cached, or sent to API endpoints. A token pasted in chat is a token leaked.

Safe input methods:

MethodHowWhen to use
read -sMasked terminal input (no echo)Scripts, CLI setup
File inputWrite token to a file (chmod 600), read from thereVault, .env files, secrets.env
GUI dialogzenity --password, kdialog, tkinter PasswordBoxDesktop environments, WSL
Environment variableVAULT_PASS="..." bash script.shNon-interactive / CI

All token-accepting scripts in this repo use masked input (ask-passphrase.sh auto-detects the best method for your platform) or environment variables. The first-run onboarding collects credentials through file edits or the vault -- never through chat.

If a token is accidentally pasted in chat: Rotate it immediately. Assume it is compromised.

Secret typeWhere it goes
MCP server tokens~/.mcp.json (local, gitignored)
Project-specific secrets.env files (add to .gitignore)
Portable secretsEncrypted vault (setup/secrets/vault.json.enc)

Vault (optional)

Encrypted credential storage that travels with the repo:

cp setup/secrets/vault.json.example setup/secrets/vault.json
# Add your tokens
bash setup/secrets/vault-manage.sh encrypt
# On another machine:
bash setup/secrets/vault-manage.sh deploy

vault.json is gitignored. Only the encrypted .enc file is committed.

Before pushing

  • Scan git diff --cached for tokens and passwords
  • No .env files staged
  • No plaintext vault files staged
  • Run bash sync.sh check-template to scan for personal data leaks

Context Budget

The system uses approximately 18-28% of a 200k-token context window at session start:

CategoryEst. tokensNotes
Claude Code system prompt~15-20kBuilt-in, not controllable
MCP tool schemas~3-5kScales with number of active servers
Global CLAUDE.md~3-5kLoading rules, conventions, shortcuts
Foundation files~2-3kUser profile, session protocol
MCP catalog (if loaded)~4kServer details, troubleshooting
Machine file~1kPlatform-specific state
Project CLAUDE.md~1-2kPer-project manifest
Startup tool calls~5-15kFile reads, git pull, inbox check
Total at startup~35-55k~18-28% of 200k

The context-budget.sh hook injects CONTEXT_BUDGET: NN% used (Xk/Yk) on every turn, so the agent self-monitors and suggests /clear when the window fills up.

More rules at startup means fewer mistakes and corrections later (which also consume tokens). Finding the right balance depends on your workflow. A minimal setup (2-3 MCP servers, short profile) sits at the low end. Ten MCP servers and detailed machine files push toward the high end.


Troubleshooting

Start here: Describe the problem to the agent. It has built-in troubleshooting knowledge for all its infrastructure -- MCP servers, permissions, session state, sync, symlinks. Most issues resolve in one exchange.

If you need to dig in manually:

ProblemWhat to check
Agent doesn't see MCP serversRestart Claude Code (MCP loads at startup). Or check if settings.local.json has an enabledMcpjsonServers whitelist filtering your server out.
GitHub returns "Not Found" on private reposThe env var must be GITHUB_PERSONAL_ACCESS_TOKEN (not GITHUB_TOKEN). Check ~/.mcp.json.
Permission prompts every sessionProject .claude/settings.local.json has a permissions block that replaces (not extends) global permissions. Remove it.
Session state not persistingRun from a directory with session-context.md or from ~/agent-fleet/.
Symlinks broken after git pullbash sync.sh setup recreates them.
Two sessions on same projectSession lock detects this and puts the second session in follower mode.
General health checkbash sync.sh status
Template drift checkbash sync.sh check shows what's drifted from template.

License

MIT -- see LICENSE.

Ver o original no GitHub

Bom para

Relacionados