Metadata-Version: 2.4
Name: scc-cli
Version: 1.5.1
Summary: Run Claude Code in Docker sandboxes with team configs and git worktree support
Project-URL: Homepage, https://github.com/CCimen/scc
Project-URL: Documentation, https://github.com/CCimen/scc#readme
Project-URL: Repository, https://github.com/CCimen/scc
Project-URL: Issues, https://github.com/CCimen/scc/issues
Author-email: Cagri Cimen <cagricimeenn@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,cli,docker,git,worktree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.25.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: readchar>=4.0.0
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">SCC - Sandboxed Claude CLI</h1>

<p align="center">
  <a href="https://pypi.org/project/scc-cli/"><img src="https://img.shields.io/pypi/v/scc-cli?style=flat-square&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/scc-cli/"><img src="https://img.shields.io/pypi/pyversions/scc-cli?style=flat-square&label=Python" alt="Python"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License: MIT"></a>
  <a href="#contributing"><img src="https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=flat-square" alt="Contributions Welcome"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> ·
  <a href="#commands">Commands</a> ·
  <a href="docs/CLI-REFERENCE.md">CLI Reference</a> ·
  <a href="#configuration">Configuration</a> ·
  <a href="docs/ARCHITECTURE.md">Architecture</a>
</p>

---

Run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding CLI) in Docker sandboxes with organization-managed team profiles and git worktree support.

SCC isolates AI execution in containers, enforces branch safety, and prevents destructive git commands. Organizations distribute plugins through a central config—developers get standardized setups without manual configuration.

> **Plugin Marketplace:** Extend Claude with the [official plugin marketplace](https://github.com/CCimen/sandboxed-code-plugins). Start with [**scc-safety-net**](docs/MARKETPLACE.md#safety-net-plugin) to block destructive git commands like `push --force`.

## 30-Second Guide

**Requires:** Python 3.10+, Docker Desktop 4.50+, Git 2.30+

```bash
pip install scc-cli      # Install
scc setup                # Configure (paste your org URL, pick your team)
cd ~/project && scc      # Auto-detect workspace and launch (or scc start ~/project)
```

Run `scc doctor` to verify your environment or troubleshoot issues.

### Smart Start Flow

When you run `scc` or `scc start` from inside a git repository:
- **Auto-detects workspace** from your current directory
- **Shows Quick Resume** if you have recent sessions for this workspace
- **Prints brief context** (workspace name, branch, team) before launching

**Keyboard shortcuts in interactive mode:**
- `Enter` — Select/resume session
- `n` — Start new session
- `Esc` — Go back
- `q` — Quit

---

### Find Your Path

| You are... | Start here |
|------------|------------|
| **Developer** joining a team | [Developer Onboarding](#developer-onboarding) — what you get automatically |
| **Team Lead** setting up your team | [Team Setup](#team-setup) — manage plugins in your own repo |
| **Org Admin** configuring security | [Organization Setup](#organization-setup) — control what's allowed org-wide |
| Exploring **plugins** | [Plugin Marketplace](docs/MARKETPLACE.md) — official plugins & safety tools |

---

### Developer Onboarding

**New to a team?** After running `scc setup` and `scc start`, you get:

- **Your team's approved plugins and MCP servers** — pre-configured and ready
- **Organization security policies** — applied automatically, no action needed
- **Command guardrails** — block destructive git commands like `push --force` (when scc-safety-net plugin is enabled)
- **Isolated git worktrees** — your main branch stays clean while Claude experiments

**What you never need to do:**
- Edit config files manually
- Download or configure plugins
- Worry about security settings

Your org admin and team lead handle the configuration. You just code.

---

### Who Controls What

| Setting | Org Admin | Team Lead | Developer |
|---------|:---------:|:---------:|:---------:|
| Block dangerous plugins/servers | ✅ **Sets** | ❌ Cannot override | ❌ Cannot override |
| Default plugins for all teams | ✅ **Sets** | — | — |
| Team-specific plugins | ✅ Approves | ✅ **Chooses** | — |
| Project-local config (.scc.yaml) | ✅ Can restrict | ✅ Can restrict | ✅ **Extends** |
| Safety-net policy (block/warn) | ✅ **Sets** | ❌ Cannot override | ❌ Cannot override |

Organization security blocks cannot be overridden by teams or developers.

*"Approves" = teams can only select from org-allowed marketplaces; blocks always apply. "Extends" = can add plugins/settings, cannot remove org defaults.*

---

### Organization Setup

Org admins create a single JSON config that controls security for all teams:

```json
{
  "schema_version": "1.0.0",
  "organization": { "name": "Acme Corp", "id": "acme" },
  "marketplaces": {
    "sandboxed-code-official": {
      "source": "github",
      "owner": "CCimen",
      "repo": "sandboxed-code-plugins"
    }
  },
  "security": {
    "blocked_plugins": ["*malicious*"],
    "blocked_mcp_servers": ["*.untrusted.com"],
    "safety_net": { "action": "block" }
  },
  "defaults": {
    "allowed_plugins": ["*"],
    "network_policy": "unrestricted"
  },
  "profiles": {
    "backend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] },
    "frontend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] }
  }
}
```

Host this anywhere: GitHub, GitLab, S3, or any HTTPS URL. Private repos work with token auth.

See [examples/](examples/) for complete org configs and [GOVERNANCE.md](docs/GOVERNANCE.md) for delegation rules.

---

### Team Setup

Teams can manage their plugins **two ways**:

**Option A: Inline (simple)** — Team config lives in the org config file.
```json
"profiles": {
  "backend": {
    "additional_plugins": ["scc-safety-net@sandboxed-code-official"]
  }
}
```

**Option B: Team Repo (GitOps)** — Team maintains their own config repo.
```json
"profiles": {
  "backend": {
    "config_source": {
      "source": "github",
      "owner": "acme",
      "repo": "backend-team-scc-config"
    }
  }
}
```

With Option B, team leads can update plugins via PRs to their own repo—no org admin approval needed for allowed additions.

**Config precedence:** Org defaults → Team profile → Project `.scc.yaml` (additive merge; blocks apply after merge).

---

## Commands

### Essential Commands

| Command | Description |
|---------|-------------|
| `scc` | Smart start: auto-detect workspace, show Quick Resume, or launch |
| `scc setup` | Configure organization connection |
| `scc doctor` | Check system health and diagnose issues |
| `scc stop` | Stop running sandbox(es) |

### Session & Team

| Command | Description |
|---------|-------------|
| `scc start --resume` | Resume most recent session |
| `scc start --select` | Pick from recent sessions |
| `scc team switch` | Switch to a different team profile |
| `scc sessions` | List recent sessions |

### Worktrees

| Command | Description |
|---------|-------------|
| `scc worktree create <repo> <name>` | Create git worktree for parallel development |
| `scc worktree enter [target]` | Enter worktree in subshell (no shell config needed) |
| `scc worktree list -v` | List worktrees with git status |

### Governance & Admin

| Command | Description |
|---------|-------------|
| `scc config explain` | Show effective config with sources |
| `scc exceptions list` | View active exceptions |
| `scc audit plugins` | Audit installed plugins |
| `scc support bundle` | Generate support bundle for troubleshooting |

Run `scc <command> --help` for options. See **[CLI Reference](docs/CLI-REFERENCE.md)** for the complete command list (40+ commands).

### Git Worktrees

**Primary method (no shell config needed):**

```bash
scc worktree enter feature-auth   # Opens a subshell in the worktree
# Type 'exit' to return to your previous directory
```

**Power users:** Add this shell wrapper for seamless `cd` switching:

```bash
# Add to ~/.bashrc or ~/.zshrc
wt() {
  local p
  p="$(scc worktree switch "$@")" || return $?
  cd "$p" || return 1
}
```

**Usage examples (both methods):**

```bash
scc worktree enter ^        # Enter main branch worktree
scc worktree enter -        # Enter previous worktree (like cd -)
wt feature-auth             # Switch with shell wrapper
wt scc/feature-x            # Match by full branch name
```

**Note:** Branch names with `/` are sanitized to `-` (e.g., `feature/auth` → `feature-auth`).

**Status indicators in `list -v`:**

| Symbol | Meaning |
|--------|---------|
| `+N` | N staged files |
| `!N` | N modified files |
| `?N` | N untracked files |
| `.` | Clean worktree |
| `…` | Status timed out |

**Cleanup stale entries:**

```bash
scc worktree prune -n   # Dry-run: show what would be pruned
scc worktree prune      # Actually prune stale entries
```

---

## Configuration

### Setup Modes

**Organization mode** (recommended):
```bash
scc setup
# Enter URL when prompted: https://gitlab.example.org/devops/scc-config.json
```

**Standalone mode** (no org config):
```bash
scc setup --standalone
```

### Project Config

Add `.scc.yaml` to your repository root for project-specific settings:

```yaml
additional_plugins:
  - "project-linter@internal"

session:
  timeout_hours: 4
```

### File Locations

```
~/.config/scc/config.json    # Org URL, team, preferences
~/.cache/scc/                # Cache (safe to delete)
<repo>/.scc.yaml             # Project-specific config
```

---

## Troubleshooting

Run `scc doctor` to diagnose issues.

| Problem | Solution |
|---------|----------|
| Docker not reachable | Start Docker Desktop |
| Organization config fetch failed | Check URL and token |
| Plugin blocked | Check `scc config explain` for security blocks |

See [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more solutions.

---

## Documentation

- [CLI Reference](docs/CLI-REFERENCE.md) — complete command reference (40+ commands)
- [Architecture](docs/ARCHITECTURE.md) — system design, module structure
- [Governance](docs/GOVERNANCE.md) — delegation model, security boundaries
- [Marketplace](docs/MARKETPLACE.md) — plugin distribution and safety-net
- [Troubleshooting](docs/TROUBLESHOOTING.md) — common problems and solutions
- [Examples](examples/) — ready-to-use organization config templates

---

## Automation & CI

SCC supports non-interactive operation for CI/CD pipelines and scripting.

```bash
# CI pipeline example
scc start --non-interactive --team backend ~/project

# Preview configuration as JSON
scc start --dry-run --json

# Full automation mode
scc start --dry-run --json --non-interactive ~/project
```

**Key flags:**
- `--non-interactive` — Fail fast instead of prompting
- `--json` — Machine-readable output with standardized envelope
- `--dry-run` — Preview configuration without launching

**Exit codes:** 0 (success), 2 (usage error), 3 (config error), 4 (tool error), 5 (prerequisites), 6 (governance block), 130 (cancelled)

See [CLI Reference → Exit Codes](docs/CLI-REFERENCE.md#exit-codes) for complete documentation.

---

## Development

```bash
uv sync              # Install dependencies
uv run pytest        # Run tests
uv run ruff check    # Run linter
```

---

## License

MIT
