{"id":30348990,"url":"https://github.com/kgn/claude_agent_environment","last_synced_at":"2025-10-04T21:57:46.027Z","repository":{"id":308612184,"uuid":"1033425875","full_name":"kgn/claude_agent_environment","owner":"kgn","description":"Claude Agent Environment (CAE)","archived":false,"fork":false,"pushed_at":"2025-08-06T21:20:58.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-06T22:25:12.658Z","etag":null,"topics":["agent","ai","claude"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kgn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-06T19:50:06.000Z","updated_at":"2025-08-06T21:21:01.000Z","dependencies_parsed_at":"2025-08-06T22:25:16.113Z","dependency_job_id":"d4214a93-94a5-4273-9ca9-a612ce81b185","html_url":"https://github.com/kgn/claude_agent_environment","commit_stats":null,"previous_names":["kgn/claude_agent_environment"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kgn/claude_agent_environment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgn%2Fclaude_agent_environment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgn%2Fclaude_agent_environment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgn%2Fclaude_agent_environment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgn%2Fclaude_agent_environment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kgn","download_url":"https://codeload.github.com/kgn/claude_agent_environment/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgn%2Fclaude_agent_environment/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271050907,"owners_count":24691186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","claude"],"created_at":"2025-08-18T19:46:24.580Z","updated_at":"2025-10-04T21:57:40.992Z","avatar_url":"https://github.com/kgn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Agent Environment\n\nA powerful tool for managing multi-repository development workflows with Claude AI. This script automates the process of checking out branches across multiple repositories, creating a structured workspace, and launching Claude with contextual information about your development task.\n\n## Features\n\n- 🚀 **Multi-Repository Management**: Clone or update multiple repositories simultaneously\n- 🌿 **Smart Branch Handling**: Automatically creates or checks out branches across all repositories\n- 📝 **Claude Integration**: Generates CLAUDE.md files with task context and launches Claude CLI\n- 🎫 **Ticket Integration**: Extracts ticket IDs from branch names and links to issue trackers\n- ⚙️ **Configurable**: JSON-based configuration for easy customization\n- 🏗️ **Organized Workspace**: Clones repositories directly to your current working directory\n\n## Installation\n\n### Quick Installation\n\nRun this one-line command:\n```bash\ncurl -sSL https://raw.githubusercontent.com/kgn/claude_agent_environment/main/install.sh | bash\n```\n\nThis will:\n- Install the package to `~/.claude_agent_environment`\n- Add `cae` to your PATH automatically\n- Provide next steps for configuration\n\nAfter installation, either open a new terminal or run `source ~/.zshrc` (or `~/.bashrc` for bash).\n\n### Manual Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/kgn/claude_agent_environment.git\ncd claude_agent_environment\n```\n\n2. Run the setup script:\n```bash\n./setup.sh\n```\n\nOr install with pip directly:\n```bash\npip install -e .\n```\n\n## Setup\n\n1. Navigate to your project root directory (where you want branches to be created):\n```bash\ncd ~/Development/my-workspace\n```\n\n2. Create a `cae_config.json` file in this directory (see example below in Configuration section)\n\n3. Edit `cae_config.json` with your organization's repositories (see Configuration section below)\n\n4. (Optional) Install Claude CLI if you want automatic launching:\n```bash\n# Follow Claude's installation instructions\n```\n\n## Configuration\n\nEdit `cae_config.json` to match your organization's setup:\n\n```json\n{\n  \"repositories\": {\n    \"frontend\": {\n      \"url\": \"https://github.com/your-org/frontend\",\n      \"type\": \"node\",\n      \"setup\": \"npm install\",\n      \"build\": \"npm run build\",\n      \"test\": \"npm run test\"\n    },\n    \"backend\": {\n      \"url\": \"https://github.com/your-org/backend\",\n      \"type\": \"python\",\n      \"setup\": \"pip install -r requirements.txt\",\n      \"build\": \"python -m build\",\n      \"test\": \"pytest\"\n    },\n    \"docs\": {\n      \"url\": \"https://github.com/your-org/documentation\",\n      \"type\": \"markdown\"\n    }\n  },\n  \"linear_base_url\": \"https://linear.app/your-workspace/issue\",\n  \"ticket_prefixes\": [\"eng\", \"bug\", \"feat\"]\n}\n```\n\n### Configuration Fields\n\n- **repositories**: Define your repositories with their URLs and optional build/test commands\n  - `url`: GitHub repository URL (required)\n  - `type`: Repository type (e.g., node, python, swift)\n  - `setup`: Setup command to run after checkout (e.g., `npm install`, `pip install -r requirements.txt`) (optional)\n  - `build`: Build command (optional)\n  - `test`: Test command (optional)\n- **linear_base_url**: Linear workspace URL for ticket linking (optional)\n- **ticket_prefixes**: Prefixes used in your branch naming convention (e.g., eng-123, bug-456)\n\n**Note**: \n- The GitHub organization name is automatically extracted from repository URLs\n- A directory named after your branch is created in the current working directory\n- Repositories are cloned into this branch directory\n- This allows you to organize your workspaces however you prefer\n\n## Usage\n\n### Basic Usage\n\n1. Navigate to your workspace root:\n```bash\ncd ~/Development/my-workspace\n```\n\n2. Check out a branch across multiple repositories:\n```bash\ncae feature/new-feature frontend backend docs\n```\n\nThe tool will automatically:\n- Clone or update each repository\n- Checkout the specified branch\n- Run the setup command if configured (e.g., `npm install` for Node projects)\n\n### With Ticket-Based Branches\n\n```bash\ncae eng-123-implement-new-feature frontend backend\n```\n\nThis will:\n1. Create a directory named after the branch in your current working directory\n2. Clone or update the specified repositories\n3. Check out or create the branch in each repository\n4. Run setup commands if configured (e.g., `npm install`, `pip install -r requirements.txt`)\n5. Generate a CLAUDE.md file with:\n   - Branch information\n   - Ticket links (if detected)\n   - Repository URLs\n   - Build and test commands\n6. Launch Claude CLI in the workspace directory\n\n### Examples\n\n```bash\n# Feature development across frontend and backend\ncae feature/user-authentication frontend backend\n\n# Bug fix in mobile app  \ncae bug-456-fix-login-crash mobile backend\n\n# Documentation update\ncae docs/api-updates docs backend\n\n# Using a Linear ticket ID directly\ncae eng-123 frontend backend provider\n```\n\n## Directory Structure\n\nAfter running `cae`, you'll have:\n\n```\nmy-workspace/\n├── cae_config.json        # Your configuration\n└── claude_template.md     # Optional custom template\n\nCurrent working directory/\n└── feature-branch-name/      # Directory created by cae\n    ├── CLAUDE.md            # Context file for Claude\n    ├── frontend/            # Repository 1  \n    ├── backend/             # Repository 2\n    └── docs/                # Repository 3\n\n~/.claude_agent_environment/\n└── [tool installation files]\n```\n\n## CLAUDE.md File\n\nThe generated CLAUDE.md file provides Claude with:\n- Branch and ticket information\n- Links to issue trackers\n- Repository URLs\n- Build and test commands for each repository\n- Task checklist\n- Implementation notes\n\nThis context helps Claude understand your development environment and provide more accurate assistance.\n\n### Customizing the CLAUDE.md Template\n\nYou can customize the CLAUDE.md template by editing `claude_template.md`. The template uses Python string formatting with the following placeholders:\n\n- `{branch_name}` - The current branch name\n- `{ticket_section}` - Ticket information (if detected)\n- `{ticket_reference}` - Reference to the ticket in text\n- `{repositories_list}` - List of repositories with URLs\n- `{test_commands}` - Test commands for each repository\n- `{build_commands}` - Build commands for each repository\n\nEdit the template to match your team's workflow and documentation style.\n\n## Advanced Usage\n\n### Adding New Repositories\n\nSimply add them to your `config.json`:\n\n```json\n\"new-service\": {\n  \"url\": \"https://github.com/your-org/new-service\",\n  \"type\": \"go\",\n  \"setup\": \"go mod download\",\n  \"build\": \"go build ./...\",\n  \"test\": \"go test ./...\"\n}\n```\n\n### Working with Multiple Projects\n\nYou can have different cae_config.json files in different directories:\n\n```bash\n# Project A\ncd ~/Development/project-a\n# Has its own cae_config.json with project-a repositories\ncae feature/new-feature frontend backend\n\n# Project B  \ncd ~/Development/project-b\n# Has its own cae_config.json with project-b repositories\ncae feature/new-feature api web mobile\n```\n\n### Repository Types\n\nSupported repository types with appropriate build/test commands:\n- `node`: Node.js/JavaScript projects\n- `python`: Python projects\n- `swift`: iOS/macOS projects\n- `go`: Go projects\n- `rust`: Rust projects\n- `java`: Java projects\n- `markdown`: Documentation repositories (typically no build/test needed)\n\n### Optional Fields\n\n- **setup**: Command to run after checkout for dependency installation (e.g., `npm install`, `pip install -r requirements.txt`)\n- **build** and **test**: Commands are optional for each repository. Omit them for repos that don't need building or testing (e.g., documentation)\n- **linear_base_url**: Only needed if you use Linear for issue tracking. Omit if using GitHub Issues or other trackers\n\n## Testing\n\nThe project includes comprehensive unit tests to ensure reliability and catch regressions.\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with verbose output\nmake test-verbose\n\n# Run tests with coverage report\nmake test-coverage\n\n# Or using pytest directly\npython -m pytest tests/\n```\n\n### Test Coverage\n\nThe test suite covers:\n- **Repository validation**: Checking if repositories exist, handling 404 errors\n- **Branch handling**: Creating new branches, checking out existing branches, handling conflicts\n- **Error handling**: Interactive prompts, --continue-on-error flag, partial failures\n- **Utility functions**: Ticket ID extraction, configuration parsing\n\nCurrent test coverage: ~78%\n\n### Development Setup\n\nTo set up the development environment with test dependencies:\n\n```bash\n# Install package with development dependencies\npip install -e \".[dev]\"\n\n# This installs:\n# - pytest: Test framework\n# - pytest-cov: Coverage reporting\n# - pytest-mock: Mocking utilities\n# - black: Code formatter\n# - ruff: Linter\n```\n\n### Continuous Integration\n\nThe project uses GitHub Actions for automated testing on:\n- Multiple Python versions (3.8, 3.9, 3.10, 3.11)\n- Multiple operating systems (Ubuntu, macOS)\n\nTests run automatically on every push and pull request to the main branch.\n\n## Troubleshooting\n\n### Common Installation Issues\n\n#### Outdated pip warning\nIf you see a warning about pip being outdated:\n```bash\npython3 -m pip install --upgrade pip\n```\n\n#### Permission denied during installation\nIf pip fails with permission errors, use the `--user` flag:\n```bash\npip install -e . --user\n```\n\n#### Command not found: cae\nAfter installation, if `cae` command is not found:\n\n1. **Check if it was installed to a non-PATH directory:**\n   ```bash\n   # macOS\n   find ~/Library/Python -name \"cae\"\n   \n   # Linux\n   find ~/.local/bin -name \"cae\"\n   ```\n\n2. **Add the directory to your PATH:**\n   ```bash\n   # Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)\n   export PATH=\"$HOME/Library/Python/3.x/bin:$PATH\"  # Replace 3.x with your Python version\n   ```\n\n3. **Or create an alias:**\n   ```bash\n   alias cae=\"/path/to/cae\"  # Use the path from step 1\n   ```\n\n### Runtime Issues\n\n#### Claude CLI not launching\n- Verify Claude is installed: `which claude`\n- The script will try to find Claude in common locations\n- Try running Claude manually: `cd your-branch \u0026\u0026 claude`\n\n#### Permission denied when cloning repositories\n- Ensure you have SSH keys set up for GitHub\n- Or use HTTPS URLs with authentication in your `cae_config.json`\n\n#### Branch already exists\nThe script will automatically check out existing branches and pull the latest changes.\n\n#### Configuration file not found\nCreate a `cae_config.json` in your project root directory. See the Configuration section above for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\nDavid Keegan - [davidkeegan.com](https://davidkeegan.com)\n\n## Acknowledgments\n\n- Built for use with [Claude Code](https://www.anthropic.com/claude-code) by Anthropic\n- Designed to streamline multi-repository development workflows","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgn%2Fclaude_agent_environment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkgn%2Fclaude_agent_environment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgn%2Fclaude_agent_environment/lists"}