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**:
-
-- 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.
+**Requirements**: You must be a repository admin to install the GitHub app and add secrets.
 
 ### 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.
-
-**When you may want to use a custom GitHub App:**
-
-- You need more restrictive permissions than the official app
+If you prefer not to install the official Claude app, you can create your own GitHub App. This is useful when:
 - 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
-   - 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 a private key** and download the `.pem` file
 
-2. **Generate and download a private key:**
+3. **Install the app** on your repositories
 
-   - After creating the app, scroll down to "Private keys"
-   - Click "Generate a private key"
-   - Download the `.pem` file (keep this secure!)
+4. **Add credentials** to repository secrets:
+   - `APP_ID`: Your app's ID
+   - `APP_PRIVATE_KEY`: Contents of the `.pem` file
 
-3. **Install the app on your repository:**
-
-   - 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:**
+5. **Update your workflow:**
 
    ```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
@@ -170,7 +145,6 @@ jobs:
 | `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                           | No\*     | -         |
 | `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                           | No\*     | -         |
 | `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                | No       | -         |
-| `override_prompt`              | Complete replacement of Claude's prompt with custom template (supports variable substitution)                        | No       | -         |
 | `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                           | No       | -         |
 | `max_turns`                    | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges)                               | No       | -         |
 | `timeout_minutes`              | Timeout in minutes for execution                                                                                     | No       | `30`      |
@@ -283,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**:
-
-- 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.
+**Important**: Your custom servers will override any built-in servers with the same name.
 
 ## Examples
 
@@ -396,43 +367,21 @@ jobs:
 
 Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance.
 
-#### Custom Prompt Templates
-
-Use `override_prompt` for complete control over Claude's behavior with variable substitution:
-
-```yaml
-- uses: anthropics/claude-code-action@beta
-  with:
-    override_prompt: |
-      Analyze PR #$PR_NUMBER in $REPOSITORY for security vulnerabilities.
-
-      Changed files:
-      $CHANGED_FILES
-
-      Focus on:
-      - SQL injection risks
-      - XSS vulnerabilities
-      - Authentication bypasses
-      - Exposed secrets or credentials
-
-      Provide severity ratings (Critical/High/Medium/Low) for any issues found.
-```
-
-The `override_prompt` feature supports these variables:
-
-- `$REPOSITORY`, `$PR_NUMBER`, `$ISSUE_NUMBER`
-- `$PR_TITLE`, `$ISSUE_TITLE`, `$PR_BODY`, `$ISSUE_BODY`
-- `$PR_COMMENTS`, `$ISSUE_COMMENTS`, `$REVIEW_COMMENTS`
-- `$CHANGED_FILES`, `$TRIGGER_COMMENT`, `$TRIGGER_USERNAME`
-- `$BRANCH_NAME`, `$BASE_BRANCH`, `$EVENT_TYPE`, `$IS_PR`
-
 ## How It Works
 
-1. **Trigger Detection**: Listens for comments containing the trigger phrase (default: `@claude`) or issue assignment to a specific user
-2. **Context Gathering**: Analyzes the PR/issue, comments, code changes
-3. **Smart Responses**: Either answers questions or implements changes
-4. **Branch Management**: Creates new PRs for human authors, pushes directly for Claude's own PRs
-5. **Communication**: Posts updates at every step to keep you informed
+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, and repository structure
+3. **Smart Responses**: Claude can:
+   - Answer questions about code and architecture
+   - 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).
 
@@ -883,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

@@ -50,10 +50,6 @@ inputs:
     description: "Direct instruction for Claude (bypasses normal trigger detection)"
     required: false
     default: ""
-  override_prompt:
-    description: "Complete replacement of Claude's prompt with custom template (supports variable substitution)"
-    required: false
-    default: ""
   mcp_config:
     description: "Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers"
   additional_permissions:
@@ -146,7 +142,6 @@ runs:
         DISALLOWED_TOOLS: ${{ inputs.disallowed_tools }}
         CUSTOM_INSTRUCTIONS: ${{ inputs.custom_instructions }}
         DIRECT_PROMPT: ${{ inputs.direct_prompt }}
-        OVERRIDE_PROMPT: ${{ inputs.override_prompt }}
         MCP_CONFIG: ${{ inputs.mcp_config }}
         OVERRIDE_GITHUB_TOKEN: ${{ inputs.github_token }}
         GITHUB_RUN_ID: ${{ github.run_id }}
@@ -193,7 +188,7 @@ runs:
       shell: bash
       run: |
         # Install Claude Code globally
-        npm install -g @anthropic-ai/claude-code@1.0.57
+        npm install -g @anthropic-ai/claude-code@1.0.56
 
         # Run the base-action
         cd ${GITHUB_ACTION_PATH}/base-action

base-action/action.yml

@@ -115,7 +115,7 @@ runs:
 
     - name: Install Claude Code
       shell: bash
-      run: npm install -g @anthropic-ai/claude-code@1.0.57
+      run: npm install -g @anthropic-ai/claude-code@1.0.56
 
     - name: Run Claude Code Action
       shell: bash

src/create-prompt/index.ts

@@ -120,7 +120,6 @@ export function prepareContext(
   const allowedTools = context.inputs.allowedTools;
   const disallowedTools = context.inputs.disallowedTools;
   const directPrompt = context.inputs.directPrompt;
-  const overridePrompt = context.inputs.overridePrompt;
   const isPR = context.isPR;
 
   // Get PR/Issue number from entityNumber
@@ -159,7 +158,6 @@ export function prepareContext(
       disallowedTools: disallowedTools.join(","),
     }),
     ...(directPrompt && { directPrompt }),
-    ...(overridePrompt && { overridePrompt }),
     ...(claudeBranch && { claudeBranch }),
   };
 
@@ -462,76 +460,11 @@ function getCommitInstructions(
   }
 }
 
-function substitutePromptVariables(
-  template: string,
-  context: PreparedContext,
-  githubData: FetchDataResult,
-): string {
-  const { contextData, comments, reviewData, changedFilesWithSHA } = githubData;
-  const { eventData } = context;
-
-  const variables: Record<string, string> = {
-    REPOSITORY: context.repository,
-    PR_NUMBER:
-      eventData.isPR && "prNumber" in eventData ? eventData.prNumber : "",
-    ISSUE_NUMBER:
-      !eventData.isPR && "issueNumber" in eventData
-        ? eventData.issueNumber
-        : "",
-    PR_TITLE: eventData.isPR && contextData?.title ? contextData.title : "",
-    ISSUE_TITLE: !eventData.isPR && contextData?.title ? contextData.title : "",
-    PR_BODY: eventData.isPR && contextData?.body ? contextData.body : "",
-    ISSUE_BODY: !eventData.isPR && contextData?.body ? contextData.body : "",
-    PR_COMMENTS: eventData.isPR
-      ? formatComments(comments, githubData.imageUrlMap)
-      : "",
-    ISSUE_COMMENTS: !eventData.isPR
-      ? formatComments(comments, githubData.imageUrlMap)
-      : "",
-    REVIEW_COMMENTS: eventData.isPR
-      ? formatReviewComments(reviewData, githubData.imageUrlMap)
-      : "",
-    CHANGED_FILES: eventData.isPR
-      ? formatChangedFilesWithSHA(changedFilesWithSHA)
-      : "",
-    TRIGGER_COMMENT: "commentBody" in eventData ? eventData.commentBody : "",
-    TRIGGER_USERNAME: context.triggerUsername || "",
-    BRANCH_NAME:
-      "claudeBranch" in eventData && eventData.claudeBranch
-        ? eventData.claudeBranch
-        : "baseBranch" in eventData && eventData.baseBranch
-          ? eventData.baseBranch
-          : "",
-    BASE_BRANCH:
-      "baseBranch" in eventData && eventData.baseBranch
-        ? eventData.baseBranch
-        : "",
-    EVENT_TYPE: eventData.eventName,
-    IS_PR: eventData.isPR ? "true" : "false",
-  };
-
-  let result = template;
-  for (const [key, value] of Object.entries(variables)) {
-    const regex = new RegExp(`\\$${key}`, "g");
-    result = result.replace(regex, value);
-  }
-
-  return result;
-}
-
 export function generatePrompt(
   context: PreparedContext,
   githubData: FetchDataResult,
   useCommitSigning: boolean,
 ): string {
-  if (context.overridePrompt) {
-    return substitutePromptVariables(
-      context.overridePrompt,
-      context,
-      githubData,
-    );
-  }
-
   const {
     contextData,
     comments,

src/create-prompt/types.ts

@@ -7,7 +7,6 @@ export type CommonFields = {
   allowedTools?: string;
   disallowedTools?: string;
   directPrompt?: string;
-  overridePrompt?: string;
 };
 
 type PullRequestReviewCommentEvent = {

src/github/context.ts

@@ -34,7 +34,6 @@ export type ParsedGitHubContext = {
     disallowedTools: string[];
     customInstructions: string;
     directPrompt: string;
-    overridePrompt: string;
     baseBranch?: string;
     branchPrefix: string;
     useStickyComment: boolean;
@@ -64,7 +63,6 @@ export function parseGitHubContext(): ParsedGitHubContext {
       disallowedTools: parseMultilineInput(process.env.DISALLOWED_TOOLS ?? ""),
       customInstructions: process.env.CUSTOM_INSTRUCTIONS ?? "",
       directPrompt: process.env.DIRECT_PROMPT ?? "",
-      overridePrompt: process.env.OVERRIDE_PROMPT ?? "",
       baseBranch: process.env.BASE_BRANCH,
       branchPrefix: process.env.BRANCH_PREFIX ?? "claude/",
       useStickyComment: process.env.USE_STICKY_COMMENT === "true",

test/create-prompt.test.ts

@@ -322,148 +322,6 @@ describe("generatePrompt", () => {
     expect(prompt).toContain("CUSTOM INSTRUCTIONS:\nAlways use TypeScript");
   });
 
-  test("should use override_prompt when provided", () => {
-    const envVars: PreparedContext = {
-      repository: "owner/repo",
-      claudeCommentId: "12345",
-      triggerPhrase: "@claude",
-      overridePrompt: "Simple prompt for $REPOSITORY PR #$PR_NUMBER",
-      eventData: {
-        eventName: "pull_request",
-        eventAction: "opened",
-        isPR: true,
-        prNumber: "123",
-      },
-    };
-
-    const prompt = generatePrompt(envVars, mockGitHubData, false);
-
-    expect(prompt).toBe("Simple prompt for owner/repo PR #123");
-    expect(prompt).not.toContain("You are Claude, an AI assistant");
-  });
-
-  test("should substitute all variables in override_prompt", () => {
-    const envVars: PreparedContext = {
-      repository: "test/repo",
-      claudeCommentId: "12345",
-      triggerPhrase: "@claude",
-      triggerUsername: "john-doe",
-      overridePrompt: `Repository: $REPOSITORY
-      PR: $PR_NUMBER
-      Title: $PR_TITLE
-      Body: $PR_BODY
-      Comments: $PR_COMMENTS
-      Review Comments: $REVIEW_COMMENTS
-      Changed Files: $CHANGED_FILES
-      Trigger Comment: $TRIGGER_COMMENT
-      Username: $TRIGGER_USERNAME
-      Branch: $BRANCH_NAME
-      Base: $BASE_BRANCH
-      Event: $EVENT_TYPE
-      Is PR: $IS_PR`,
-      eventData: {
-        eventName: "pull_request_review_comment",
-        isPR: true,
-        prNumber: "456",
-        commentBody: "Please review this code",
-        claudeBranch: "feature-branch",
-        baseBranch: "main",
-      },
-    };
-
-    const prompt = generatePrompt(envVars, mockGitHubData, false);
-
-    expect(prompt).toContain("Repository: test/repo");
-    expect(prompt).toContain("PR: 456");
-    expect(prompt).toContain("Title: Test PR");
-    expect(prompt).toContain("Body: This is a test PR");
-    expect(prompt).toContain("Comments: ");
-    expect(prompt).toContain("Review Comments: ");
-    expect(prompt).toContain("Changed Files: ");
-    expect(prompt).toContain("Trigger Comment: Please review this code");
-    expect(prompt).toContain("Username: john-doe");
-    expect(prompt).toContain("Branch: feature-branch");
-    expect(prompt).toContain("Base: main");
-    expect(prompt).toContain("Event: pull_request_review_comment");
-    expect(prompt).toContain("Is PR: true");
-  });
-
-  test("should handle override_prompt for issues", () => {
-    const envVars: PreparedContext = {
-      repository: "owner/repo",
-      claudeCommentId: "12345",
-      triggerPhrase: "@claude",
-      overridePrompt: "Issue #$ISSUE_NUMBER: $ISSUE_TITLE in $REPOSITORY",
-      eventData: {
-        eventName: "issues",
-        eventAction: "opened",
-        isPR: false,
-        issueNumber: "789",
-        baseBranch: "main",
-        claudeBranch: "claude/issue-789-20240101-1200",
-      },
-    };
-
-    const issueGitHubData = {
-      ...mockGitHubData,
-      contextData: {
-        title: "Bug: Login form broken",
-        body: "The login form is not working",
-        author: { login: "testuser" },
-        state: "OPEN",
-        createdAt: "2023-01-01T00:00:00Z",
-        comments: {
-          nodes: [],
-        },
-      },
-    };
-
-    const prompt = generatePrompt(envVars, issueGitHubData, false);
-
-    expect(prompt).toBe("Issue #789: Bug: Login form broken in owner/repo");
-  });
-
-  test("should handle empty values in override_prompt substitution", () => {
-    const envVars: PreparedContext = {
-      repository: "owner/repo",
-      claudeCommentId: "12345",
-      triggerPhrase: "@claude",
-      overridePrompt:
-        "PR: $PR_NUMBER, Issue: $ISSUE_NUMBER, Comment: $TRIGGER_COMMENT",
-      eventData: {
-        eventName: "pull_request",
-        eventAction: "opened",
-        isPR: true,
-        prNumber: "123",
-      },
-    };
-
-    const prompt = generatePrompt(envVars, mockGitHubData, false);
-
-    expect(prompt).toBe("PR: 123, Issue: , Comment: ");
-  });
-
-  test("should not substitute variables when override_prompt is not provided", () => {
-    const envVars: PreparedContext = {
-      repository: "owner/repo",
-      claudeCommentId: "12345",
-      triggerPhrase: "@claude",
-      eventData: {
-        eventName: "issues",
-        eventAction: "opened",
-        isPR: false,
-        issueNumber: "123",
-        baseBranch: "main",
-        claudeBranch: "claude/issue-123-20240101-1200",
-      },
-    };
-
-    const prompt = generatePrompt(envVars, mockGitHubData, false);
-
-    expect(prompt).toContain("You are Claude, an AI assistant");
-    expect(prompt).toContain("<event_type>ISSUE_CREATED</event_type>");
-  });
-
   test("should include trigger username when provided", () => {
     const envVars: PreparedContext = {
       repository: "owner/repo",

test/install-mcp-server.test.ts

@@ -31,7 +31,6 @@ describe("prepareMcpConfig", () => {
       disallowedTools: [],
       customInstructions: "",
       directPrompt: "",
-      overridePrompt: "",
       branchPrefix: "",
       useStickyComment: false,
       additionalPermissions: new Map(),

test/mockContext.ts

@@ -16,7 +16,6 @@ const defaultInputs = {
   disallowedTools: [] as string[],
   customInstructions: "",
   directPrompt: "",
-  overridePrompt: "",
   useBedrock: false,
   useVertex: false,
   timeoutMinutes: 30,

test/permissions.test.ts

@@ -67,7 +67,6 @@ describe("checkWritePermissions", () => {
       disallowedTools: [],
       customInstructions: "",
       directPrompt: "",
-      overridePrompt: "",
       branchPrefix: "claude/",
       useStickyComment: false,
       additionalPermissions: new Map(),

test/trigger-validation.test.ts

@@ -32,7 +32,6 @@ describe("checkContainsTrigger", () => {
           assigneeTrigger: "",
           labelTrigger: "",
           directPrompt: "Fix the bug in the login form",
-          overridePrompt: "",
           allowedTools: [],
           disallowedTools: [],
           customInstructions: "",
@@ -64,7 +63,6 @@ describe("checkContainsTrigger", () => {
           assigneeTrigger: "",
           labelTrigger: "",
           directPrompt: "",
-          overridePrompt: "",
           allowedTools: [],
           disallowedTools: [],
           customInstructions: "",
@@ -280,7 +278,6 @@ describe("checkContainsTrigger", () => {
           assigneeTrigger: "",
           labelTrigger: "",
           directPrompt: "",
-          overridePrompt: "",
           allowedTools: [],
           disallowedTools: [],
           customInstructions: "",
@@ -313,7 +310,6 @@ describe("checkContainsTrigger", () => {
           assigneeTrigger: "",
           labelTrigger: "",
           directPrompt: "",
-          overridePrompt: "",
           allowedTools: [],
           disallowedTools: [],
           customInstructions: "",
@@ -346,7 +342,6 @@ describe("checkContainsTrigger", () => {
           assigneeTrigger: "",
           labelTrigger: "",
           directPrompt: "",
-          overridePrompt: "",
           allowedTools: [],
           disallowedTools: [],
           customInstructions: "",