# Workspace Configuration
Augent workspaces are your working Git repositories where bundles are installed and configured. This document explains workspace structure, configuration files, and how bundles integrate into workspaces.
---
## Overview
A **workspace** is a Git repository containing:
- Augent configuration in `.augent/` directory
- Installed resources in AI coding platform directories
- Metadata tracking which bundles provide which resources
Augent automatically initializes workspaces when needed.
---
## Workspace Structure
```text
my-project/
├── .augent/ # Augent workspace directory
│ ├── augent.yaml # Workspace bundle definition
│ ├── augent.lock # Locked bundle versions
│ └── augent.index.yaml # Resource tracking
├── .claude/ # Claude Code configuration
├── .cursor/ # Cursor configuration
├── .opencode/ # OpenCode configuration
├── CLAUDE.md # Claude Code agent config
├── AGENTS.md # Shared agent configuration
└── ... # Your project files
```
---
## Configuration Files
Configuration files are located in `.augent/` directory. See [Bundles spec](implementation/specs/bundles.md) for details.
### augent.yaml
Defines **direct** bundles installed in the workspace. Each entry is stored in a canonical form (not the install source string). Bundle order is preserved; later bundles override earlier ones when files overlap.
**The workspace name is not stored in augent.yaml**. It is automatically inferred from the workspace location:
- Git repositories: `@owner/repo` (extracted from git remote)
- Non-git directories: `@username/directory-name` (fallback)
**Directory bundle** (name = directory name):
```yaml
bundles:
- name: local-bundle
path: ./local-bundle
```
**Git bundle** (name = `@owner/repo` or `@owner/repo/bundle-name` or `@owner/repo:path`; ref is stored in the lockfile, not in the name):
```yaml
bundles:
- name: '@owner/repo'
git: https://github.com/owner/repo.git
```
Dependencies of dependencies are not listed in `augent.yaml`; they appear only in `augent.lock`.
### augent.lock
Auto-generated lockfile with all bundles (direct and transitive) in installation order. Every Git bundle has `ref` and the **exact SHA** of the commit for reproducibility. See [Bundles spec](implementation/specs/bundles.md) and [ADR-003: Locking Mechanism](implementation/adrs/003-locking-mechanism.md).
**Never manually edit** — updated on install.
### augent.index.yaml
Tracks which bundles provide which resources, in installation order (including resources from dependencies). Each bundle lists its **bundle-relative paths** (e.g. `rules/debug.md`) and the **installed platform paths** (e.g. `.claude/rules/debug.md`). Augent uses this for conflict detection, modification tracking, and uninstallation.
**Optional:** This file is automatically generated. If deleted or missing, Augent will rebuild it by scanning installed files.
---
## Lazy Workspace Configuration
Augent can work without `augent.index.yaml`. When missing:
- **On Install**: Augent generates the workspace config file automatically
- **On Uninstall**: Augent scans the workspace to rebuild the config by detecting platforms, scanning installed files, and matching them to bundles from the lockfile
This is useful when migrating from another system or if the config is corrupted.
---
## Workspace Initialization
Augent initializes workspaces automatically on first `install`:
### Auto-Detection
```bash
cd /path/to/my-git-repo
augent install github:author/bundle
# .augent/ automatically created
```
### Manual Initialization
```bash
cd /path/to/my-git-repo
augent install github:author/bundle
# Workspace initialized with inferred name from git remote
```
### Naming
Augent infers workspace name from git remote:
| `github.com/username/project` | `username/project` |
| `gitlab.com/username/project` | `username/project` |
| No remote | `<username>/<directory>` |
---
## Resource Installation
### How Resources Flow
1. **Download**: Bundle fetched to the augent cache (run `augent cache` to see the path)
2. **Transform**: Resources transformed to AI coding platform-specific format
3. **Merge**: Merged into existing resources (if applicable)
4. **Install**: Copied to AI coding platform directories
5. **Track**: Metadata added to `augent.index.yaml`
### Installation Locations
| Rules | `.cursor/rules/` (`.mdc`) | `.claude/rules/` | `.opencode/rules/` |
| Skills | `.cursor/skills/` | `.claude/skills/` | `.opencode/skills/` (each skill in `{name}/SKILL.md`) |
| Commands | `.cursor/commands/` | `.claude/commands/` | `.opencode/commands/` |
| MCP | `.cursor/mcp.json` | `.mcp.json` (project root; Claude Code) | `.opencode/opencode.json` (MCP key in main config) |
| AGENTS.md | Merged into `AGENTS.md` | Merged into `CLAUDE.md` | Merged into `AGENTS.md` |
| Root files | Copied to workspace root | | |
### Merge Strategies
| Rules/Skills/Commands | Replace | Later bundle overwrites earlier |
| MCP config (mcp.json, opencode.json) | Deep | JSON merged, later values override |
| AGENTS.md / root file | Composite | Text merged with delimiter |
| Root files | Replace | Later bundle overwrites earlier |
---
## Modified File Detection
Augent tracks modifications to prevent data loss:
### Detection Process
1. Calculate hash of original file from cached bundle
2. Compare with current workspace file hash
3. If different, file is marked as modified
4. Modified files are copied to workspace bundle directory
### Handling Modified Files
**Before uninstall:**
```bash
augent uninstall my-bundle
# Warning: Some files modified
# Modified files backed up locally
```
**Before install:**
```bash
augent install new-bundle
# Warning: New bundle would overwrite modified files
# Modified files preserved locally
```
### Checking Modifications
```bash
# Augent warns about modifications automatically
augent install github:author/new-bundle
# View workspace configuration to see tracking
cat .augent/augent.index.yaml
```
---
## Platform Detection
Augent automatically detects installed AI coding platforms:
### Detection Methods
1. **Directory Check**
- `.claude/` → Claude Code
- `.cursor/` → Cursor
- `.opencode/` → OpenCode
2. **File Check**
- `CLAUDE.md` → Claude Code
- `AGENTS.md` → Generic/OpenCode
### Installing for Specific Platforms
```bash
# Install only for specific platforms
augent install ./bundle --to cursor opencode
# Auto-detect platforms
augent install ./bundle
```
### Platform Aliases
| `claude` | `claude-code` |
| `cursor` | `cursor` |
| `opencode` | `opencode` |
---
## Locking and Reproducibility
### Lockfile Purpose
`augent.lock` ensures:
1. **Team consistency:** Same bundle versions across team
2. **Reproducibility:** Exact SHAs for all dependencies
3. **Safety:** Detects unexpected changes
### Frozen Install (CI/CD)
```bash
# Fail if lockfile would change
augent install --frozen
```
**Use cases:**
- CI/CD pipelines
- Production deployments
- Verifying exact dependencies
### Updating Lockfile
```bash
# Update to latest versions
augent install github:author/bundle
# Lockfile updated automatically
cat .augent/augent.lock
```
---
## Bundle Lifecycle
### Adding Bundles
Add to `augent.yaml` and run `augent install`:
- New bundles are resolved and added to `augent.lock` and `augent.index.yaml`
- Resources installed to platform directories
- Existing bundles in `augent.lock` are preserved with their exact SHAs (unless `--update` is used)
### Removing from Configuration
Removing from `augent.yaml` and running `augent install`:
- Bundle **IS** removed from lockfile and workspace config
- Files **ARE** uninstalled
- Use `--update` flag to re-resolve and update SHAs for all bundles
### Explicit Removal
Use `augent uninstall <name>` to completely remove:
- Files removed (unless overridden by other bundles)
- Entries removed from all config files
- Dependencies cleaned up if unused
### Configuration Files
| `augent.yaml` | Direct bundles only (name, path/git) | Install adds entry; order preserved | Manual deletion |
| `augent.lock` | All bundles (direct + transitive), ref + exact SHA | Updated first on install | `augent uninstall` |
| `augent.index.yaml` | Installed file tracking, in order | Updated after lock and yaml | `augent uninstall` |
---
## Workspace Cleanup
### Removing Bundles
```bash
augent uninstall my-bundle
# Removes bundle files
# Updates configuration
# Preserves modified files
```
### Resetting Workspace
```bash
# Remove all Augent configuration
rm -rf .augent
# Clean agent directories (optional)
rm -rf .claude .cursor .opencode
# Reinstall bundles
augent install github:author/bundle
```
### Cache Management
```bash
# Show cache statistics
augent cache
# List cached bundles
augent cache list
# Clear all cached bundles
augent cache clear
# Remove specific bundle
augent cache clear --only github.com-author-repo
```
---
## Best Practices
### Version Control
**Commit `.augent/` directory:**
```bash
git add .augent/
git commit -m "Add debug-tools bundle"
```
**Commit lockfile for reproducibility:**
```bash
git add .augent/augent.lock
git commit -m "Lock dependency versions"
```
**Don't commit:**
- Agent directories with secrets
### Bundle Ordering
**Order matters:** Put overrides last. Entries are stored in canonical form (see [Bundles spec](implementation/specs/bundles.md)):
```yaml
bundles:
- name: '@owner/base-config'
git: https://github.com/owner/base-config.git
path: .
- name: '@owner/team-standards'
git: https://github.com/owner/team-standards.git
path: .
- name: local-bundle
path: ./local-bundle
```
### Team Collaboration
1. **Share `.augent/augent.yaml`:** Defines team bundles
2. **Commit lockfile:** Ensures everyone uses same versions
3. **Document modifications:** Track manual changes to resources
4. **Use frozen installs in CI:** Prevents unexpected updates
---
## Troubleshooting
### Bundle Not Found
```bash
Error: Bundle not found: my-bundle
```
**Check:**
- Bundle name is correct
- Bundle is installed (`augent list`)
- Case sensitivity matters
### Conflicts
```bash
Warning: File already provided by another bundle
```
**Resolution:**
- Check bundle order in `augent.yaml`
- Later bundles override earlier bundles
- Adjust order if needed
### Modified Files
```bash
Warning: Some files were modified
```
**Action:**
- Modified files backed up locally
- Review before uninstalling
- Manually merge if needed
### Lockfile Mismatch
```bash
Error: Lockfile would change (use --frozen to fail)
```
**Resolution:**
- Update lockfile: `augent install github:author/bundle`
- Or use `--frozen` for CI/CD
---
## See Also
- [Commands Reference](commands.md) - Managing workspaces via CLI
- [Bundle Format](bundles.md) - Creating and publishing bundles
- [Architecture Documentation](implementation/architecture.md) - Implementation details