How to Use Remote Directories

Load rules and tasks from remote locations like Git repositories, HTTP servers, or S3 buckets instead of duplicating files across projects.

Problem

You want to:

Share coding standards across multiple projects
Centralize organizational guidelines
Version control your rules separately from your code
Distribute team-specific rules without duplication

Solution

Use the -d flag to load rules and tasks from remote directories. The CLI downloads them to a temporary location, processes them, then cleans up automatically.

Basic Usage

Load from Git Repository

# Clone a Git repository containing rules
coding-context -d git::https://github.com/company/shared-rules.git fix-bug

This downloads the repository, searches for rules and tasks in standard locations (.agents/rules/, .agents/tasks/, etc.), and includes them in the context.

Use Specific Version

# Use a specific tag
coding-context -d 'git::https://github.com/company/rules.git?ref=v1.0.0' fix-bug

# Use a specific branch
coding-context -d 'git::https://github.com/company/rules.git?ref=main' fix-bug

# Use a specific commit
coding-context -d 'git::https://github.com/company/rules.git?ref=abc123def' fix-bug

Use Subdirectory

If your rules are in a subdirectory of a repository, use double slashes (//):

# Get rules from the 'coding-standards' subdirectory
coding-context -d 'git::https://github.com/company/mono-repo.git//coding-standards' fix-bug

Supported Protocols

The -d flag uses go-getter, which supports multiple protocols:

Git Repositories

# HTTPS
coding-context -d git::https://github.com/company/rules.git fix-bug

# SSH (requires SSH keys configured)
coding-context -d git::git@github.com:company/rules.git fix-bug

# With authentication token
coding-context -d 'git::https://token@github.com/company/private-rules.git' fix-bug

HTTP/HTTPS

# Download and extract tar.gz
coding-context -d https://example.com/rules.tar.gz fix-bug

# Download and extract zip
coding-context -d https://example.com/rules.zip fix-bug

S3 Buckets

# S3 bucket
coding-context -d s3::https://s3.amazonaws.com/my-bucket/rules fix-bug

# With specific region
coding-context -d s3::https://s3-us-west-2.amazonaws.com/my-bucket/rules fix-bug

Local Files

Useful for testing:

coding-context -d file:///path/to/local/rules fix-bug

Advanced Usage

Multiple Remote Sources

Combine rules from multiple locations:

coding-context \
  -d git::https://github.com/company/org-standards.git \
  -d git::https://github.com/team/team-rules.git \
  -d https://cdn.company.com/archived-rules.tar.gz \
  /fix-bug

Rules from all sources are merged together and processed as if they were in a single directory.

Mix Remote and Local

Combine remote directories with local project rules:

# Loads from:
# 1. Remote Git repository (via -d)
# 2. Working directory (automatically added)
# 3. Home directory (automatically added)
coding-context \
  -d git::https://github.com/company/shared-rules.git \
  -s languages=go \
  /fix-bug

You can also explicitly add local directories:

# Explicitly add a local directory
coding-context \
  -d git::https://github.com/company/shared-rules.git \
  -d file:///path/to/local/rules \
  -s languages=go \
  /fix-bug

Note: The working directory (-C or current directory) and home directory are automatically added to search paths, so you don’t need to specify them explicitly.

With Selectors and Parameters

Use remote directories with all normal CLI features:

coding-context \
  -d git::https://github.com/company/standards.git \
  -s languages=go \
  -s environment=production \
  -p component=auth \
  -p severity=critical \
  /fix-security-issue | llm -m claude-3-5-sonnet-20241022

Repository Structure

Your remote repository should follow the same structure as local directories:

shared-rules/
├── .agents/
│   ├── rules/
│   │   ├── coding-standards.md
│   │   ├── security-guidelines.md
│   │   └── testing-requirements.md
│   └── tasks/
│       ├── code-review.md
│       └── fix-security-issue.md
└── README.md

The CLI searches for standard locations:

.agents/rules/ - Rule files
.agents/tasks/ - Task files
AGENTS.md, CLAUDE.md, etc. - Single-file rules
.github/copilot-instructions.md - GitHub Copilot rules
And all other standard search paths

Example Repository

Here’s a complete example of setting up a shared rules repository:

1. Create Repository

# Create repository
mkdir shared-coding-rules
cd shared-coding-rules
git init

# Create directory structure
mkdir -p .agents/rules
mkdir -p .agents/tasks

2. Add Rules

.agents/rules/go-standards.md:

---
languages:
  - go
---

# Go Coding Standards

- Use `gofmt` for formatting
- Write tests for all public functions
- Handle all errors explicitly
- Use meaningful variable names

.agents/rules/security.md:

# Security Guidelines

- Never commit secrets or API keys
- Validate all user input
- Use prepared statements for SQL
- Keep dependencies up to date

3. Add Tasks

.agents/tasks/code-review.md:

# Code Review Task

Review the code changes for:
- Adherence to coding standards
- Security vulnerabilities
- Test coverage
- Documentation

4. Publish

# Commit and push
git add .
git commit -m "Initial coding standards"
git tag v1.0.0
git remote add origin https://github.com/company/shared-coding-rules.git
git push -u origin main
git push --tags

5. Use in Projects

# In any project
coding-context \
  -d 'git::https://github.com/company/shared-coding-rules.git?ref=v1.0.0' \
  -s languages=go \
  /code-review

Bootstrap Scripts

Bootstrap scripts work in remote directories:

Remote repository:

.agents/
├── rules/
│   ├── jira-context.md
│   └── jira-context-bootstrap  # Executable script

The jira-context-bootstrap script runs before processing the rule, just like with local files.

Important Notes

Performance

Remote directories are downloaded on each invocation
Use specific tags/commits for reproducible builds
Git shallow clones are used automatically (faster downloads)

Caching

Remote directories are not cached between runs. Each invocation downloads fresh:

# Downloads repository
coding-context -d git::https://github.com/company/rules.git fix-bug

# Downloads again (not cached)
coding-context -d git::https://github.com/company/rules.git code-review

For better performance with frequently-used remote directories, consider:

Cloning locally and using file:// protocol
Using a CI/CD cache
Hosting on a fast CDN

Cleanup

Downloaded directories are automatically cleaned up after execution. No manual cleanup needed.

Authentication

Git over HTTPS with token:

export GITHUB_TOKEN="ghp_your_token_here"
coding-context -d "git::https://${GITHUB_TOKEN}@github.com/company/private-rules.git" fix-bug

Git over SSH:

# Uses your SSH keys from ~/.ssh/
coding-context -d git::git@github.com:company/private-rules.git fix-bug

S3 with AWS credentials:

# Uses AWS credentials from environment or ~/.aws/credentials
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
coding-context -d s3::https://s3.amazonaws.com/my-bucket/rules fix-bug

Troubleshooting

“Failed to download remote directory”

Check:

URL is accessible (test with git clone or curl)
Authentication is configured (tokens, SSH keys)
Correct protocol prefix (git::, s3::, etc.)
Network connectivity

Example:

# Test Git URL
git clone https://github.com/company/rules.git /tmp/test-clone

# Test HTTP URL
curl -I https://example.com/rules.tar.gz

“No rules found”

The remote directory might not have the expected structure.