Project Configuration

You can add a .scc.yaml file to your repository root to customize SCC settings for that specific project.

When to Use Project Config

Use .scc.yaml when you need:

• Project-specific plugins
• Custom session timeouts
• Entry directory overrides
• Team pinning for the project

Note

Project configuration extends your team config. You cannot override organization security blocks or remove team defaults.

File Location

• Directorymy-project/

  • .scc.yaml ← Project config
  • Directory.git/

    • …
  • Directorysrc/

    • …
  • package.json

Basic Structure

.scc.yaml

# Add plugins specific to this project
additional_plugins:
  - "eslint-plugin@internal"
  - "project-linter@team-marketplace"

# Override session settings
session:
  timeout_hours: 4

# Pin this project to a specific team
team: backend

Available Options

Additional Plugins

Add plugins beyond what your team provides:

additional_plugins:
  - "plugin-name@marketplace"
  - "another-plugin@marketplace"

Caution

You can only add plugins that match your team’s allow_additional_plugins patterns. Attempts to add disallowed plugins will be blocked.

Session Settings

Override session behavior:

session:
  timeout_hours: 4      # Override team default
  auto_resume: false    # Disable auto-resume

Team Pinning

Force a specific team profile for this project:

team: security

When developers open this project with scc, it will use the security team’s configuration regardless of their default team.

Entry Directory

Specify a different entry point:

entry_directory: ./packages/frontend

Claude Code will start in this directory instead of the project root.

Example Configurations

Monorepo Frontend Package

.scc.yaml

# Pin to frontend team
team: frontend

# Start in the frontend package
entry_directory: ./packages/frontend

# Add React-specific tooling
additional_plugins:
  - "react-tools@frontend-marketplace"

session:
  timeout_hours: 8

Security-Sensitive Project

.scc.yaml

# Force security team config (strictest settings)
team: security

# Short sessions for sensitive work
session:
  timeout_hours: 2
  auto_resume: false

Data Science Project

.scc.yaml

# Use ML team profile
team: ml-team

# Longer sessions for training runs
session:
  timeout_hours: 24

# Add data science plugins
additional_plugins:
  - "jupyter-helper@ml-marketplace"
  - "pandas-tools@ml-marketplace"

Validation

Validate your project config:

scc config validate

This checks:

• YAML syntax is correct
• Referenced plugins are allowed
• Team exists (if pinned)
• All settings are recognized

Seeing Effective Config

To see how project config combines with team and org settings:

scc config explain

Output shows the source of each setting:

Effective configuration for ~/project:

plugins:
  - scc-safety-net        (from: team/backend)
  - code-formatter        (from: team/backend)
  - eslint-plugin         (from: project/.scc.yaml)  ← Project addition

session:
  timeout_hours: 4        (from: project/.scc.yaml)  ← Project override
  auto_resume: true       (from: team/backend)

network_policy: corp-proxy-only (from: org/defaults)

What You Cannot Override

Project config cannot:

• Remove team default plugins
• Unblock organization-blocked plugins
• Override network policy (if org restricts it)
• Bypass security settings

Danger

Organization security blocks are absolute. Even if you try to add a blocked plugin in .scc.yaml, it will be filtered out.

Git Ignore Considerations

The .scc.yaml file should typically be committed to your repository so all team members get the same project settings.

However, if you have personal overrides, you can create a local file:

# Add to .git/info/exclude (not committed)
.scc.local.yaml

Note

Local overrides (.scc.local.yaml) are only supported if your team enables allow_project_overrides: true.

Personal Profiles (Local)

If you want your own plugins or MCP servers without committing anything to the repo, use personal profiles instead of .scc.local.yaml.

scc profile save
scc profile apply

Personal profiles live outside the repo and can be synced across machines. See Personal Profiles for details.

Troubleshooting

”Plugin not allowed”

Your team’s delegation rules don’t permit that plugin. Check with your team lead.

scc config explain --field delegation

”Team not found”

The pinned team doesn’t exist in your org config. Verify the team name:

scc team

Changes not taking effect

Project config is read at session start. Restart your session:

scc stop
scc start --fresh