🤖 Add documentation for Project Secrets and Agentic Git Identity (#101)

ammar-agent · ammario · web-flow · commit eddee9b7d708 · 2025-10-08T13:55:28.000-05:00
## Overview

Added comprehensive user-facing documentation for two key features:

1. **Project Secrets** - Managing environment variables for projects
2. **Agentic Git Identity** - Configuring separate Git identity for
AI-generated commits

## Changes

### Project Secrets Documentation (`docs/project-secrets.md`)
- Explains what project secrets are and common use cases
- Step-by-step guide for managing secrets via the UI
- Security considerations and best practices
- Troubleshooting common issues

### Agentic Git Identity Documentation (`docs/agentic-git-identity.md`)
- Complete setup guide for using separate GitHub account for AI commits
- Instructions for generating Classic GitHub tokens (simpler than
fine-grained)
- Git credential helper configuration to prevent keychain conflicts
- Environment variable setup for author/committer identity
- Comprehensive troubleshooting section

## Testing

Both documents have been added to `docs/SUMMARY.md` for proper
navigation.

_Generated with `cmux`_

---------

Co-authored-by: Ammar Bandukwala &lt;ammar@ammar.io&gt;
diff --git a/README.md b/README.md
@@ -26,6 +26,31 @@ Download pre-built binaries from [GitHub Actions artifacts](https://github.com/c
 
 See [AGENTS.md](./AGENTS.md) for development setup and guidelines.
 
+### Documentation Style Guide
+
+When writing user-facing documentation, follow these principles:
+
+**Minimum Viable Documentation** - Write only what users need to complete their task successfully. Assume users are:
+
+- Capable of using basic UIs without instruction
+- Able to debug issues without pre-written troubleshooting
+- Smart enough to apply security best practices without being told
+
+**Delete:**
+
+- Step-by-step UI walkthroughs for obvious interactions ("Click the button", "Enter the value", "Click Save")
+- Troubleshooting sections for hypothetical problems that haven't occurred
+- Best practices and security advice (users will research when needed)
+- Multiple ways to do the same thing (pick one, preferably the simplest)
+- Verification/testing sections
+
+**Keep:**
+
+- Core setup steps with technical details
+- Non-obvious facts about how things work
+- Actual command examples
+- Brief, clear explanations
+
 ## Features
 
 - 🔀 Git worktree integration for multi-branch workflows
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -4,4 +4,6 @@
 - [Install](./install.md)
 - [Keyboard Shortcuts](./keybinds.md)
 - [Context Management](./context-management.md)
+- [Project Secrets](./project-secrets.md)
+- [Agentic Git Identity](./agentic-git-identity.md)
 - [AGENTS](./AGENTS.md)
diff --git a/docs/agentic-git-identity.md b/docs/agentic-git-identity.md
@@ -0,0 +1,99 @@
+# Agentic Git Identity
+
+Configure cmux to use a separate Git identity for AI-generated commits, making it easy to distinguish between human and AI contributions. Reasons to use a separate identity include:
+
+- Clear attribution
+- Preventing (accidental) destructive actions
+- Enforcing review flow, e.g. preventing AI from merging into `main` while allowing humans
+
+## Setup Overview
+
+1. Create a GitHub account for your agent (e.g., `username-agent`)
+2. Generate a Classic GitHub token
+3. Configure Git to use the agent identity
+4. Configure Git credentials to use the token
+
+## Step 1: Create Agent GitHub Account
+
+Create a separate GitHub account for your agent:
+
+1. Sign up at [github.com/signup](https://github.com/signup)
+2. Use a distinctive username (e.g., `yourname-agent`, `yourname-ai`)
+3. Use a separate email (GitHub allows plus-addressing: `yourname+ai@example.com`)
+
+> **Note**: This is optional but recommended. You can also use your main account with a different email/name.
+
+## Step 2: Generate Classic GitHub Token
+
+Classic tokens are easier to configure than fine-grained tokens for repository access.
+
+1. Log into your agent GitHub account
+2. Go to [Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
+3. Click "Generate new token (classic)"
+4. Configure the token:
+   - **Note**: "cmux agent token" (or similar)
+   - **Expiration**: Choose based on your security preferences
+   - **Scopes**: Select `repo` (Full control of private repositories)
+5. Click "Generate token"
+6. **Copy the token immediately** - you won't see it again
+
+## Step 3: Configure Git Identity
+
+Add the Git identity environment variables as [Project Secrets](./project-secrets.md) in cmux:
+
+1. Open cmux and find your project in the sidebar
+2. Click the 🔑 key icon to open the secrets modal
+3. Add the following four secrets:
+   - `GIT_AUTHOR_NAME` = `Your Name (Agent)`
+   - `GIT_AUTHOR_EMAIL` = `yourname+ai@example.com`
+   - `GIT_COMMITTER_NAME` = `Your Name (Agent)`
+   - `GIT_COMMITTER_EMAIL` = `yourname+ai@example.com`
+4. Click "Save"
+
+These environment variables will be automatically injected when the agent runs Git commands in that project.
+
+> **Note**: If you need the agent identity outside of cmux, you can alternatively set these as global environment variables in your shell configuration (`~/.zshrc`, `~/.bashrc`, etc.)
+
+## Step 4: Configure GitHub Authentication
+
+### Install GitHub CLI
+
+If you don't have it:
+
+```bash
+# macOS
+brew install gh
+
+# Windows
+winget install --id GitHub.cli
+
+# Linux
+# See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+```
+
+### Configure Git Credential Helper
+
+Set up Git to use the GitHub CLI for authentication. The recommended approach is to use `gh auth setup-git`, which scopes the credential helper to GitHub only:
+
+```bash
+# Configure gh as credential helper for GitHub (recommended)
+gh auth setup-git
+```
+
+This configures Git to use `gh` for GitHub authentication while preserving your existing credential helpers for other Git hosts.
+
+**Alternative: Manual configuration (for advanced users)**
+
+If you need more control or want to completely replace existing credential helpers:
+
+```bash
+# Scope to GitHub only (preserves other credential helpers)
+git config --global credential.https://github.com.helper '!gh auth git-credential'
+
+# OR: Replace all credential helpers (may break non-GitHub authentication)
+git config --global --unset-all credential.helper
+git config --global credential.helper ""
+git config --global --add credential.helper '!gh auth git-credential'
+```
+
+⚠️ **Warning**: The "replace all" approach will disable platform keychain helpers and may break Git authentication for non-GitHub remotes (GitLab, Bitbucket, etc.).
diff --git a/docs/img/project-secrets.webp b/docs/img/project-secrets.webp
diff --git a/docs/project-secrets.md b/docs/project-secrets.md
@@ -0,0 +1,54 @@
+# Project Secrets
+
+Securely manage environment variables for your projects in cmux. Project secrets are automatically injected when the agent executes bash commands, making it easy to provide API keys, tokens, and other sensitive configuration.
+
+![Project Secrets Modal](./img/project-secrets.webp)
+
+## What Are Project Secrets?
+
+Project secrets are key-value pairs stored per project that are:
+
+- **Automatically injected** as environment variables when running bash commands
+- **Stored outside repo** in `~/.cmux/secrets.json`
+- **Project-scoped** - each project has its own set of secrets
+- **Workspace-inherited** - all workspaces in a project use the same secrets
+
+## Common Use Cases
+
+- **API Keys**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GITHUB_TOKEN`
+- **Authentication tokens**: `NPM_TOKEN`, `DOCKER_HUB_TOKEN`
+- **Database credentials**: `DATABASE_URL`, `POSTGRES_PASSWORD`
+- **Service endpoints**: `API_BASE_URL`, `WEBHOOK_URL`
+- **Build configuration**: `BUILD_ENV`, `FEATURE_FLAGS`
+
+## Managing Secrets
+
+### Opening the Secrets Modal
+
+1. Find your project in the left sidebar
+2. Hover over the project name
+3. Click the 🔑 key icon that appears
+
+## How Secrets Are Used
+
+When the agent runs bash commands (via the `bash` tool), all project secrets are automatically injected as environment variables:
+
+```bash
+# If you have a secret: GH_TOKEN=ghp_abc123
+# The agent can use it in commands:
+gh api /user  # Uses GH_TOKEN from environment
+```
+
+The agent doesn't need to explicitly reference secrets - they're available as regular environment variables in all bash executions within that project's workspaces.
+
+## Security Considerations
+
+### Storage
+
+- Secrets are stored in `~/.cmux/config.json`
+- **Stored in plaintext** - the config file is not encrypted
+- The config file has standard user-only file permissions
+
+## Related
+
+- [Agentic Git Identity](./agentic-git-identity.md) - Configure Git credentials for AI commits using Project Secrets
diff --git a/scripts/lint.sh b/scripts/lint.sh
@@ -14,7 +14,11 @@ if [ -n "$PNG_FILES" ]; then
   echo "❌ Error: PNG files found in docs directory. Please use WebP format instead:"
   echo "$PNG_FILES"
   echo ""
-  echo "Convert with: cwebp input.png -o output.webp -q 85"
+  echo "Convert with:"
+  for png in $PNG_FILES; do
+    webp="${png%.png}.webp"
+    echo "  cwebp '$png' -o '$webp' -q 85"
+  done
   exit 1
 fi
 
