{
  "markdown": "# project-setup\n\nA Claude Code plugin that auto-discovers project tooling and configures `.claude/` accordingly.\n\nDetects virtual environments, linters, test runners, IDE settings, and additional source directories, then writes the appropriate `.claude/settings.json` and `.claude/CLAUDE.md` configuration.\n\n## Rationale\n\nYour IDE already knows your project: the virtual environment, the linters, the test runner, the source roots. But Claude doesn't — without explicit configuration it falls back to generic assumptions, misses project-specific tooling, and can't access dependency sources sitting one directory over.\n\nThis plugin bridges that gap. It reads what your IDE and project files already declare, then writes the matching `.claude/` configuration so Claude uses the right interpreter, runs the right linter, and has access to the right directories — no manual setup required.\n\n## Features\n\n- **Environment detection** — Python venvs (standard, Poetry, Pipenv, PDM, uv), Node.js, Rust, Go\n- **IDE settings** — Extracts hints from VSCode, PyCharm, Vim/Neovim, Emacs configs\n- **Linter detection** — pre-commit, ruff, black, mypy, eslint, prettier, clippy, golangci-lint, and more\n- **Test runner detection** — pytest, tox, nox, jest, vitest, cargo test, go test\n- **Directory detection** — Monorepo workspaces, git submodules, IDE source roots, symlinks\n\n## Installation\n\nSee the [official Claude Code plugin docs](https://code.claude.com/docs/en/plugins) for general guidance on installing and managing plugins.\n\n```bash\nclaude plugin install claude-code-project-setup\n```\n\nOr install from the repository directly:\n\n```bash\nclaude plugin install /path/to/project-setup\n```\n\n### Try without installing (session-only)\n\nTo test the plugin without installing it, load it for a single session:\n\n```bash\ncd /your/project\nclaude --plugin-dir /path/to/project-setup\n```\n\nThe plugin is active only for that session. Commands are namespaced by the plugin name, so run `/project-setup:project-setup` instead of `/project-setup`.\n\n## Usage\n\n### Automatic Setup on Session Start\n\nWhen the plugin is installed, it automatically detects when you start a new Claude Code session in a project without `.claude/settings.json` or `CLAUDE.md`. The hook injects a message into Claude's context suggesting `/project-setup:project-setup`.\n\n**Limitations:**\n- The message is not displayed in the terminal UI (e.g., \"Recent activity\" or \"Tips\"). It's added to Claude's context, so Claude will see the suggestion when you send your first message.\n- The `/init` command cannot be hooked — there's no hook event for built-in CLI commands. If you run `/init`, it creates a basic `CLAUDE.md` without the tooling detection this plugin provides. Run `/project-setup:project-setup` instead or afterwards for full configuration.\n\nIf your project is already configured, the hook stays silent.\n\n### Testing with a PyCharm project\n\n1. Open a terminal in your PyCharm project root (the folder containing `.idea/`)\n2. Launch Claude with the plugin:\n   ```bash\n   cd /your/pycharm/project\n   claude --plugin-dir /path/to/project-setup\n   ```\n3. Inside the session, run a dry run first:\n   ```\n   /project-setup:project-setup --dry-run\n   ```\n\nThe plugin reads `.idea/*.iml` (source roots), `misc.xml` (Python interpreter), and `runConfigurations/*.xml` (test setup). If the output looks right, apply it:\n\n```\n/project-setup:project-setup\n```\n\n**Note:** The plugin only detects folders that PyCharm has registered as modules in `.idea/modules.xml`. If you have multiple folders open in PyCharm but they aren't configured as modules (e.g. you opened them informally alongside the main project), the plugin won't find them. In that case, add them manually — see [Manual directory configuration](#manual-directory-configuration) below.\n\n### Auto-configure a project\n\n```\n/project-setup:project-setup\n```\n\nRuns all detectors, shows a summary of findings, and asks for approval before writing configuration files.\n\n### Dry run (no writes)\n\n```\n/project-setup:project-setup --dry-run\n```\n\nRuns detection and shows the proposed changes without writing any files.\n\n### Validate existing configuration\n\n```\n/project-setup:check\n```\n\nChecks that all referenced paths, tools, and commands in `.claude/settings.json` and `.claude/CLAUDE.md` actually work.\n\n### Copy configuration from another project\n\n```\n/project-setup:copy-from [/path/to/source-project] [--dry-run]\n```\n\nReads `.claude/` configuration from a source project and adapts it for the current project. Rather than a verbatim copy, paths, environments, and tool references are remapped:\n\n- **Virtual environment** — the source venv path is replaced with the one detected in the current project.\n- **Additional directories** — each source directory is matched to an equivalent relative to the current project root. If the mapping is ambiguous you'll be asked to confirm.\n- **Allowed commands** — tool commands (e.g. `Bash(pytest *)`) are kept only if the same tool is present; substitutions are made when the current project uses an equivalent (e.g. `pnpm` instead of `npm`).\n- **CLAUDE.md sections** — `## Environment`, `## Linting`, and `## Testing` are regenerated from fresh detection; other sections are copied and paths are rewritten.\n\nIf no path is given, the command will ask for one. Use `--dry-run` to preview changes without writing any files.\n\n#### Testing copy-from\n\n1. Open a terminal in the **target** project (e.g. `src/projectK`) — it does not need an existing `.claude/`\n2. Launch Claude with the plugin:\n   ```bash\n   cd src/projectK\n   claude --plugin-dir /path/to/project-setup\n   ```\n3. Run a dry run first:\n   ```\n   /project-setup:copy-from ../projectA --dry-run\n   ```\n4. Check the summary — the \"Adapted\" section should show path remapping, not just \"Copied as-is\"\n5. If the output looks right, apply it:\n   ```\n   /project-setup:copy-from ../projectA\n   ```\n\n**What to check in the output:**\n\n| Scenario | Expected result |\n|---|---|\n| Source has a venv path | Replaced with target project's venv, not copied verbatim |\n| Source `additionalDirectories` exist near target | Carried over automatically |\n| Source `additionalDirectories` don't exist near target | Warned and dropped |\n| Source `additionalDirectories` have an ambiguous match | You are prompted to confirm |\n| Target has `permissions.deny` entries | Unchanged after copy |\n\n## Configuration\n\nCreate `.claude/project-setup.local.md` to customize behavior:\n\n```yaml\n---\ndir-permission-default: read\n---\n```\n\n`dir-permission-default` controls what permissions are granted for discovered additional directories:\n- `read` (default) — adds `Read`, `Glob`, `Grep`\n- `read-only` — adds `Read` only (no search tools)\n- `edit` — adds `Read`, `Glob`, `Grep`, `Edit`, `Write`\n- `full` — adds `Read`, `Glob`, `Grep`, `Edit`, `Write`, `Bash(*)`\n\n## Manual directory configuration\n\nIf the plugin can't detect your extra directories automatically, or you want to fine-tune what it produced, edit `.claude/settings.json` in your project root directly.\n\n### Multi-project example\n\nIf you have several sibling projects (e.g. `src/projectA`, `src/projectR`, `src/projectK`) and want Claude to work across all of them from `projectK`:\n\n```json\n{\n  \"permissions\": {\n    \"additionalDirectories\": [\n      \"../projectA\",\n      \"../projectR\"\n    ],\n    \"allow\": [\n      \"Bash(pytest *)\",\n      \"Bash(pre-commit run *)\",\n      \"Read(../projectA/**)\",\n      \"Read(../projectR/**)\"\n    ]\n  },\n  \"env\": {\n    \"VIRTUAL_ENV\": \"/absolute/path/to/projectK/.venv\"\n  },\n  \"hooks\": {\n    \"SessionStart\": [\"source /absolute/path/to/projectK/.venv/bin/activate\"]\n  }\n}\n```\n\n### Fields at a glance\n\n| Field | Purpose |\n|---|---|\n| `permissions.additionalDirectories` | Directories Claude can browse freely (relative to project root) |\n| `permissions.allow` | Pre-approved tool+path combinations, so Claude doesn't prompt for each |\n| `permissions.deny` | Explicitly blocked tools or paths — **never modified by the plugin** |\n| `env.VIRTUAL_ENV` | Python virtual environment path (absolute) |\n| `hooks.SessionStart` | Shell commands run at session start, e.g. venv activation |\n\n`additionalDirectories` paths are relative to the project root. `env` and `hooks` paths must be absolute. `permissions.deny` is never touched by the plugin regardless of what other commands run.\n\n## What it writes\n\n### `.claude/settings.json`\n\n- `permissions.allow` — lint and test commands\n- `permissions.additionalDirectories` — discovered external source directories\n- `env.VIRTUAL_ENV` — Python virtual environment path\n- `hooks.SessionStart` — PATH activation for venvs\n\nExisting settings are merged, never overwritten. `permissions.deny` is never modified.\n\n### `.claude/CLAUDE.md`\n\nAppends concise sections (only if the `##` header doesn't already exist):\n- `## Environment` — language version, venv location\n- `## Linting` — canonical lint command\n- `## Testing` — canonical test command, single-test pattern\n\n## Publishing to npm\n\nThe GitHub Actions workflow publishes to npm automatically when you push a version tag:\n\n```bash\nnpm version patch  # or minor/major\ngit push --follow-tags\n```\n\n### Setup\n\n1. Create an account on https://www.npmjs.com\n2. Go to **Access Tokens** in your account settings\n3. Generate a new **Automation** token\n4. Add it as a GitHub repo secret named `NPM_TOKEN` under **Settings > Secrets and variables > Actions**\n\n## Submitting to the official directory\n\nThis plugin can be submitted to the [Anthropic Plugin Directory](https://github.com/anthropics/claude-plugins-official) for review and distribution.\n\n## License\n\nMIT\n",
  "bytes": 9610,
  "sha": "ef88e226ec17bc3263680f911b6d715215c541e3027d278b49422f1290dc65f4",
  "repo_slug": "lambdao-dev/claude-project-setup-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_lambdao_dev_claude_project_setup_plugin__d3c2b829/readme"
}