# NestDX

Secure, governed workspaces for AI-assisted development.

NestDX wraps your AI coding tools (Claude Code, Codex, Cursor, HatchDX agents, or any CLI tool) with session tracking, secrets scanning, filesystem policy enforcement, cost tracking, and CI integration — so you can move fast without leaking credentials or breaking boundaries.

## Install

```bash
# From source
pip install .

# With uv
uv pip install .
```

**Requirements:** Python 3.13+, Git

## Quick Start

```bash
# 1. Initialize a workspace (creates nestdx.yaml + .nestdx/ directory)
nestdx init my-project
nestdx init --template python        # or: typescript, default

# 2. Start a session (snapshots git state, activates file watcher)
nestdx start

# 3. Run a tool within the session
nestdx run claude-code               # named tool adapter
nestdx run codex                     # Codex adapter
nestdx run cursor                    # Cursor (GUI — blocks until you press Enter)
nestdx run hdx-agent                 # HatchDX agent
nestdx run -- pytest -x              # any CLI command via generic adapter

# 4. Stop the session (captures git diff, runs policy checks)
nestdx stop

# 5. Review what happened
nestdx log                           # full session details
nestdx log --cost                    # token/cost breakdown
nestdx audit --ci                    # re-run policy checks (exit 1 on errors)
nestdx sessions                      # list all sessions
nestdx sessions --summary            # aggregated stats
nestdx report --by-tool              # usage report
```

## Tool Setup

NestDX supports five tool adapters out of the box:

| Tool | Install | NestDX Command |
|------|---------|----------------|
| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `nestdx run claude-code` |
| **Codex** | `npm install -g @openai/codex` | `nestdx run codex` |
| **Cursor** | [cursor.com](https://cursor.com) (GUI) | `nestdx run cursor` |
| **HatchDX** | `pip install hatchdx` | `nestdx run hdx-agent` |
| **Any CLI** | On PATH | `nestdx run -- <command>` |

Configure tools in `nestdx.yaml`:

```yaml
tools:
  claude-code:
    enabled: true
    config:
      model: claude-sonnet-4-5-20250929
  codex:
    enabled: true
    config:
      model: o4-mini
  cursor:
    enabled: true
  hdx-agent:
    enabled: true
    agent_path: ./agents/my-agent    # required for HatchDX
```

## Container Mode

Run tools inside an isolated container with resource limits and network controls:

```yaml
# Add to nestdx.yaml
environment:
  base: python:3.13-slim
  setup:
    - "pip install -r requirements.txt"
  test_command: "pytest tests/ -v"
  lint_command: "ruff check src/"
  env_file: ".env.nest"
  # volumes:
  #   - "/data:/data:ro"
```

```bash
nestdx start                         # auto-detects container mode
nestdx start --local                 # force local mode
nestdx start --container             # require container mode (fail if no env config)
nestdx start --dry-run               # validate config without starting
```

Container mode requires Docker, Podman, or nerdctl on PATH.

## Network Egress Control

In container mode, restrict outbound network access to specific domains:

```yaml
policies:
  network:
    allowed_domains:
      - "pypi.org"
      - "registry.npmjs.org"
      - "api.anthropic.com"
    block_all_other_egress: true      # block all other outbound traffic
```

Network policy is enforced via iptables inside the container. In local mode, NestDX warns that the policy cannot be enforced.

## CI Integration

### GitHub Actions

Generate a workflow file automatically:

```bash
nestdx init --ci                     # creates .github/workflows/nestdx-audit.yaml
```

Or add to your existing workflow:

```yaml
- name: Run NestDX audit
  run: |
    nestdx audit --ci \
      --base-ref ${{ github.event.pull_request.base.sha }} \
      --head-ref ${{ github.event.pull_request.head.sha }} \
      --format sarif \
      > nestdx-results.sarif
- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: nestdx-results.sarif
```

The audit command:
- Diffs files between two git refs
- Scans for secrets and policy violations
- Outputs SARIF, JSON, or Rich (terminal) format
- Exits with code 1 when error-level violations are found

## Reporting

```bash
nestdx report                        # last 30 days, Rich table
nestdx report --days 7               # last 7 days
nestdx report --by-tool              # breakdown by tool
nestdx report --by-engineer          # breakdown by git author
nestdx report --format json          # JSON output
nestdx report --format csv           # CSV output
```

Session data is stored as JSON (source of truth) with a SQLite index for fast aggregation queries.

## Configuration Reference

Full `nestdx.yaml` schema:

```yaml
name: my-project
version: "0.1.0"

# --- Environment (optional — enables container mode) ---
environment:
  base: python:3.13-slim             # base Docker image
  setup:                             # commands to run during image build
    - "pip install -r requirements.txt"
  test_command: "pytest tests/ -v"   # optional: test runner
  lint_command: "ruff check src/"    # optional: linter
  env_file: ".env.nest"             # optional: env vars file (never committed)
  dockerfile: "./Dockerfile.nest"    # optional: custom Dockerfile
  volumes:                           # optional: extra volume mounts
    - "/data:/data:ro"
  cache_dirs:                        # optional: cache directories
    - "~/.cache/uv"
    - "~/.cache/pip"

# --- Tools ---
tools:
  claude-code:
    enabled: true
    config:
      model: claude-sonnet-4-5-20250929
      max_tokens: 8096
  codex:
    enabled: true
    config:
      model: o4-mini
      provider: openai
  cursor:
    enabled: true
  hdx-agent:
    enabled: true
    agent_path: ./agents/my-agent

# --- Policies ---
policies:
  secrets:
    scan_agent_output: true
    scan_commits: true
    block_patterns:                   # regex patterns for secret detection
      - "AWS_SECRET_ACCESS_KEY\\s*=\\s*\\S+"
      - "PRIVATE_KEY"
      - "password\\s*=\\s*\\S+"
      - "Bearer\\s+[A-Za-z0-9\\-._~+/]{20,}"
      - "ghp_[A-Za-z0-9]{36}"
      - "sk-[A-Za-z0-9]{32,}"
    custom_patterns_file: ".nestdx-secrets.yaml"   # optional: extra patterns

  filesystem:
    read_only:                        # files agents must not modify
      - ".env*"
      - "secrets/"
      - ".git/"
      - "*.pem"
      - "*.key"
    no_write:                         # directories agents must not write to
      - "production/"
      - "deploy/"
    allowed_write:                    # explicit write-allow list
      - "src/"
      - "tests/"

  network:
    allowed_domains:                  # egress whitelist (container mode only)
      - "pypi.org"
      - "api.anthropic.com"
    block_all_other_egress: true

  resources:
    max_cpu: "2.0"                   # CPU limit (container mode)
    max_memory: "2g"                 # memory limit (container mode)
    max_session_duration: "4h"       # session timeout

# --- Tracking ---
tracking:
  log_file_changes: true
  log_commands: true
  track_tokens: true                  # parse token usage from tool output
  track_cost: true                    # estimate cost from token usage
  session_dir: ".nestdx/sessions/"
  export_format: "json"
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `nestdx init [name]` | Initialize workspace (creates `nestdx.yaml`) |
| `nestdx init --ci` | Also generate GitHub Actions workflow |
| `nestdx start` | Start a session |
| `nestdx start --dry-run` | Validate config without starting |
| `nestdx start --local` | Force local mode |
| `nestdx start --container` | Require container mode |
| `nestdx start --force` | Force-stop stale session before starting |
| `nestdx stop` | Stop session, run policy checks |
| `nestdx stop --force` | Force-stop a stale session |
| `nestdx run <tool>` | Run a named tool adapter |
| `nestdx run -- <cmd>` | Run any command via generic adapter |
| `nestdx log` | Show last session details |
| `nestdx log --cost` | Show token/cost breakdown only |
| `nestdx log -s <id>` | Show specific session |
| `nestdx audit` | Re-run policy checks on last session |
| `nestdx audit --ci` | Exit 1 on error-level violations |
| `nestdx audit --base-ref <sha>` | Diff-based audit (no session needed) |
| `nestdx audit --format sarif` | SARIF output for GitHub Security tab |
| `nestdx sessions` | List all sessions |
| `nestdx sessions --summary` | Aggregated stats |
| `nestdx report` | Usage report (last 30 days) |
| `nestdx report --by-tool` | Breakdown by tool |
| `nestdx report --format json` | JSON output |

Global flags: `--verbose` / `-v` (debug output), `--quiet` / `-q` (suppress noise)

## How It Works

```
nestdx start  →  Snapshot git state, start file watcher
                  Optionally: build + start container
                  ↓
nestdx run    →  Launch tool inside governed session
                  Track commands, capture output
                  Real-time secrets scanning (watcher)
                  ↓
nestdx stop   →  Capture git diff (files changed)
                  Run post-session policy checks
                  Record violations, cost data
                  Stop container (if running)
                  ↓
nestdx audit  →  Re-scan for secrets + policy violations
                  CI-ready: exit codes, SARIF output
```

## License

Proprietary. All rights reserved.
