docs: clean up README by removing redundancy and improving organization

- Removed duplicate Security Best Practices section that repeated authentication warnings
- Enhanced How It Works section with more detailed steps
- Streamlined Quickstart section for better clarity
- Consolidated Custom GitHub App instructions for conciseness
- Removed redundant security warnings from MCP configuration section
- Improved overall document flow and organization

Co-authored-by: Ashwin Bhat <ashwin-ant@users.noreply.github.com>

README.md

@@ -16,14 +16,16 @@ A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs an
 
 ## Quickstart
 
-The easiest way to set up this action is through [Claude Code](https://claude.ai/code) in the terminal. Just open `claude` and run `/install-github-app`.
+The easiest way to set up this action is through [Claude Code](https://claude.ai/code) in the terminal:
+
+```bash
+claude
+/install-github-app
+```
 
 This command will guide you through setting up the GitHub app and required secrets.
 
-**Note**:
+**Requirements**: You must be a repository admin to install the GitHub app and add secrets.
-
-- You must be a repository admin to install the GitHub app and add secrets
-- This quickstart method is only available for direct Anthropic API users. If you're using AWS Bedrock, please see the instructions below.
 
 ### Manual Setup (Direct API)
 
@@ -37,49 +39,27 @@ This command will guide you through setting up the GitHub app and required secre
 
 ### Using a Custom GitHub App
 
-If you prefer not to install the official Claude app, you can create your own GitHub App to use with this action. This gives you complete control over permissions and access.
+If you prefer not to install the official Claude app, you can create your own GitHub App. This is useful when:
-
-**When you may want to use a custom GitHub App:**
-
-- You need more restrictive permissions than the official app
 - Organization policies prevent installing third-party apps
+- You need more restrictive permissions
 - You're using AWS Bedrock or Google Vertex AI
 
-**Steps to create and use a custom GitHub App:**
+**Setup steps:**
 
-1. **Create a new GitHub App:**
+1. **Create a GitHub App** at https://github.com/settings/apps with these permissions:
+   - Contents: Read & Write
+   - Issues: Read & Write  
+   - Pull requests: Read & Write
 
-   - Go to https://github.com/settings/apps (for personal apps) or your organization's settings
+2. **Generate a private key** and download the `.pem` file
-   - Click "New GitHub App"
-   - Configure the app with these minimum permissions:
-     - **Repository permissions:**
-       - Contents: Read & Write
-       - Issues: Read & Write
-       - Pull requests: Read & Write
-     - **Account permissions:** None required
-   - Set "Where can this GitHub App be installed?" to your preference
-   - Create the app
 
-2. **Generate and download a private key:**
+3. **Install the app** on your repositories
 
-   - After creating the app, scroll down to "Private keys"
+4. **Add credentials** to repository secrets:
-   - Click "Generate a private key"
+   - `APP_ID`: Your app's ID
-   - Download the `.pem` file (keep this secure!)
+   - `APP_PRIVATE_KEY`: Contents of the `.pem` file
 
-3. **Install the app on your repository:**
+5. **Update your workflow:**
-
-   - Go to the app's settings page
-   - Click "Install App"
-   - Select the repositories where you want to use Claude
-
-4. **Add the app credentials to your repository secrets:**
-
-   - Go to your repository's Settings → Secrets and variables → Actions
-   - Add these secrets:
-     - `APP_ID`: Your GitHub App's ID (found in the app settings)
-     - `APP_PRIVATE_KEY`: The contents of the downloaded `.pem` file
-
-5. **Update your workflow to use the custom app:**
 
    ```yaml
    name: Claude with Custom App
@@ -108,11 +88,6 @@ If you prefer not to install the official Claude app, you can create your own Gi
              # ... other configuration
    ```
 
-**Important notes:**
-
-- The custom app must have read/write permissions for Issues, Pull Requests, and Contents
-- Your app's token will have the exact permissions you configured, nothing more
-
 For more information on creating GitHub Apps, see the [GitHub documentation](https://docs.github.com/en/apps/creating-github-apps).
 
 ## 📚 FAQ
@@ -282,10 +257,7 @@ For example, if your Python MCP server is at `mcp_servers/weather.py`, you would
   ["--directory", "${{ github.workspace }}/mcp_servers/", "run", "weather.py"]
 ```
 
-**Important**:
+**Important**: Your custom servers will override any built-in servers with the same name.
-
-- Always use GitHub Secrets (`${{ secrets.SECRET_NAME }}`) for sensitive values like API keys, tokens, or passwords. Never hardcode secrets directly in the workflow file.
-- Your custom servers will override any built-in servers with the same name.
 
 ## Examples
 
@@ -397,11 +369,19 @@ Perfect for automatically reviewing PRs from new team members, external contribu
 
 ## How It Works
 
-1. **Trigger Detection**: Listens for comments containing the trigger phrase (default: `@claude`) or issue assignment to a specific user
+1. **Trigger Detection**: Listens for comments containing the trigger phrase (default: `@claude`), issue assignments, or label applications
-2. **Context Gathering**: Analyzes the PR/issue, comments, code changes
+2. **Context Gathering**: Analyzes the PR/issue, comments, code changes, and repository structure
-3. **Smart Responses**: Either answers questions or implements changes
+3. **Smart Responses**: Claude can:
-4. **Branch Management**: Creates new PRs for human authors, pushes directly for Claude's own PRs
+   - Answer questions about code and architecture
-5. **Communication**: Posts updates at every step to keep you informed
+   - Provide detailed code reviews
+   - Implement requested changes
+   - Fix bugs and add features
+4. **Branch Management**:
+   - Creates new branches for issues
+   - Pushes directly to open PR branches
+   - Creates new branches for closed/merged PRs
+5. **Progress Tracking**: Updates a single comment with checkboxes showing task completion
+6. **Integration**: Works seamlessly with GitHub's PR and issue workflows
 
 This action is built on top of [`anthropics/claude-code-base-action`](https://github.com/anthropics/claude-code-base-action).
 
@@ -852,41 +832,6 @@ claude_code_oauth_token: "oauth_token_..." # Exposed and vulnerable!
 5. ❌ Never share API keys or tokens in pull requests or issues
 6. ❌ Avoid logging workflow variables that might contain keys
 
-## Security Best Practices
-
-**⚠️ IMPORTANT: Never commit API keys directly to your repository! Always use GitHub Actions secrets.**
-
-To securely use your Anthropic API key:
-
-1. Add your API key as a repository secret:
-
-   - Go to your repository's Settings
-   - Navigate to "Secrets and variables" → "Actions"
-   - Click "New repository secret"
-   - Name it `ANTHROPIC_API_KEY`
-   - Paste your API key as the value
-
-2. Reference the secret in your workflow:
-   ```yaml
-   anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-   ```
-
-**Never do this:**
-
-```yaml
-# ❌ WRONG - Exposes your API key
-anthropic_api_key: "sk-ant-..."
-```
-
-**Always do this:**
-
-```yaml
-# ✅ CORRECT - Uses GitHub secrets
-anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-```
-
-This applies to all sensitive values including API keys, access tokens, and credentials.
-We also recommend that you always use short-lived tokens when possible
 
 ## License
 

action.yml

@@ -193,7 +193,8 @@ runs:
         # Run the base-action
         cd ${GITHUB_ACTION_PATH}/base-action
         bun install
-        bun run src/index.ts
+        cd -
+        bun run ${GITHUB_ACTION_PATH}/base-action/src/index.ts
       env:
         # Base-action inputs
         CLAUDE_CODE_ACTION: "1"

base-action/src/index.ts

@@ -26,6 +26,7 @@ async function run() {
       appendSystemPrompt: process.env.INPUT_APPEND_SYSTEM_PROMPT,
       claudeEnv: process.env.INPUT_CLAUDE_ENV,
       fallbackModel: process.env.INPUT_FALLBACK_MODEL,
+      model: process.env.ANTHROPIC_MODEL,
     });
   } catch (error) {
     core.setFailed(`Action failed with error: ${error}`);

base-action/src/run-claude.ts

@@ -21,6 +21,7 @@ export type ClaudeOptions = {
   claudeEnv?: string;
   fallbackModel?: string;
   timeoutMinutes?: string;
+  model?: string;
 };
 
 type PreparedConfig = {
@@ -94,6 +95,9 @@ export function prepareRunConfig(
   if (options.fallbackModel) {
     claudeArgs.push("--fallback-model", options.fallbackModel);
   }
+  if (options.model) {
+    claudeArgs.push("--model", options.model);
+  }
   if (options.timeoutMinutes) {
     const timeoutMinutesNum = parseInt(options.timeoutMinutes, 10);
     if (isNaN(timeoutMinutesNum) || timeoutMinutesNum <= 0) {

src/create-prompt/index.ts

@@ -694,8 +694,7 @@ What You CANNOT Do:
 - Submit formal GitHub PR reviews
 - Approve pull requests (for security reasons)
 - Post multiple comments (you only update your initial comment)
-- Execute commands outside the repository context
+- Execute commands outside the repository context${useCommitSigning ? "\n- Run arbitrary Bash commands (unless explicitly allowed via allowed_tools configuration)" : ""}
-- Run arbitrary Bash commands (unless explicitly allowed via allowed_tools configuration)
 - Perform branch operations (cannot merge branches, rebase, or perform other git operations beyond pushing commits)
 - Modify files in the .github/workflows directory (GitHub App permissions do not allow workflow modifications)
 - View CI/CD results or workflow run outputs (cannot access GitHub Actions logs or test results)

src/github/operations/branch.ts

@@ -116,6 +116,11 @@ export async function setupBranch(
         `Branch name generated: ${newBranch} (will be created by file ops server on first commit)`,
       );
 
+      // Ensure we're on the source branch
+      console.log(`Fetching and checking out source branch: ${sourceBranch}`);
+      await $`git fetch origin ${sourceBranch} --depth=1`;
+      await $`git checkout ${sourceBranch}`;
+
       // Set outputs for GitHub Actions
       core.setOutput("CLAUDE_BRANCH", newBranch);
       core.setOutput("BASE_BRANCH", sourceBranch);
@@ -131,7 +136,12 @@ export async function setupBranch(
       `Creating local branch ${newBranch} for ${entityType} #${entityNumber} from source branch: ${sourceBranch}...`,
     );
 
-    // Create and checkout the new branch locally
+    // Fetch and checkout the source branch first to ensure we branch from the correct base
+    console.log(`Fetching and checking out source branch: ${sourceBranch}`);
+    await $`git fetch origin ${sourceBranch} --depth=1`;
+    await $`git checkout ${sourceBranch}`;
+
+    // Create and checkout the new branch from the source branch
     await $`git checkout -b ${newBranch}`;
 
     console.log(