### Preflight Checklist - [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet - [x] This is a single bug report (please file separate reports for different bugs) - [x] I am using the latest version of Claude Code ### What's Wrong? ## Summary Background tasks fail with "Background tasks require a git repository" error despite being in a valid git repository that is correctly detected

[BUG] Background Tasks Fail to Detect Valid Git Repository

Status Fixed / completed

Maintainer reply ✓ Yes — amorriscode

Activity 13 comments · opened Dec 4, 2025 · closed Jan 8, 2026

💡 Likely answer: A maintainer (amorriscode, contributor) responded on this thread — see the highlighted reply below.

Preflight Checklist

[x] I have searched existing issues and this hasn't been reported yet
[x] This is a single bug report (please file separate reports for different bugs)
[x] I am using the latest version of Claude Code

What's Wrong?

Summary

Background tasks fail with "Background tasks require a git repository" error despite being in a valid git repository that is correctly detected by the main Claude Code session.

Environment

OS: macOS 15.6.1 (Build 24G90)
Platform: darwin
Kernel: Darwin 24.6.0
Git Version: 2.39.5 (Apple Git-154)
Git Location: /usr/bin/git

Repository Information

Working Directory: /Users/Jonny/Documents/obsidian/trading
Git Repository Status: Valid and functional
Main Session Detection: ✅ Correctly detected (Is directory a git repo: Yes)
Background Task Detection: ❌ Fails with error

Expected Behavior

Background tasks should successfully detect the git repository, just as the main Claude Code session does.

Actual Behavior

Background tasks fail with a git repository detection error despite:

Being in a valid git repository
All git commands working correctly
Main session detecting the repository properly
No permission, symlink, or configuration issues

Additional Context

The repository has:

Recent commits (verified with git log)
Clean working tree
Proper .git directory structure
All standard git operations working

Analysis

This appears to be a bug in the background task system's git detection logic. The background task spawning process uses different repository detection code than the main session, and this detection is failing even though:

The repository is completely valid
All git commands execute successfully
The main Claude Code session correctly identifies it as a git repository
No environmental or permission issues exist

Suggested Investigation

The background task system should use the same git repository detection logic as the main session, or inherit the repository status from the parent session rather than re-detecting independently.

Workaround

Currently, tasks must be run sequentially using the Task tool instead of background tasks, which significantly impacts performance when processing multiple independent items.

What Should Happen?

Background tasks should successfully detect the git repository, just as the main Claude Code session does.

Error Messages/Logs

Cannot launch remote Claude Code session.

Background tasks require a git repository. Initialize git or run from a git repository.

Steps to Reproduce

Navigate to a valid git repository
Verify git repository status:

``bash git rev-parse --is-inside-work-tree # Returns: true git rev-parse --show-toplevel # Returns: /Users/Jonny/Documents/obsidian/trading``

Start Claude Code session (main session correctly detects git repo)
Attempt to run background tasks using the background task syntax
Observe error about missing git repository

Validation Performed

✅ Git Repository Validation

$ git rev-parse --is-inside-work-tree
true

$ git rev-parse --show-toplevel
/Users/Jonny/Documents/obsidian/trading

$ git rev-parse --git-dir
.git

$ git status
On branch main
nothing to commit, working tree clean

✅ Permissions Check

$ stat -f "%Sp %Su:%Sg" .git
drwxr-xr-x Jonny:staff

$ ls -la .git/
drwxr-xr-x@  13 Jonny  staff    416 Nov 30 19:49 .
drwxr-xr-x@  22 Jonny  staff    704 Nov 30 19:42 ..
-rw-r--r--@   1 Jonny  staff     11 Nov 30 19:47 COMMIT_EDITMSG
-rw-r--r--@   1 Jonny  staff    137 Nov 25 17:38 config
[... all files owned by user with proper permissions]

All .git subdirectories have proper permissions (755/drwxr-xr-x).

✅ Path Check (No Symlinks)

$ pwd
/Users/Jonny/Documents/obsidian/trading

$ pwd -P
/Users/Jonny/Documents/obsidian/trading

$ readlink -n "$(pwd)"
Not a symlink

No symlinks in the path - physical and logical paths are identical.

✅ Git Config Check

$ git config --list --local
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=true
core.precomposeunicode=true

Standard, valid git configuration with no unusual settings.

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.58 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_

View original on GitHub ↗

13 Comments

Jon-Biz · 8 months ago

I had this issue because I was unintentionally triggered background process mode, the new (to me) '&' command, that I had assigned as a prefix for my prompt snippets. Calling a prompt in the Claude console would also initiate background process mode.

However, the underlying issue - that background processes are unable to detect the git repo they are being called in, still stands.

kylesnowschwartz · 8 months ago

I face the same issue - instructions for installation unclear. Changelog suggests Added background agent support. Agents run in the background while you work but using what appears to be the entryway to that feature & <my task> just results in an error even after adding the github app

derekc00 · 7 months ago

I'm getting the same error

danielfaust · 7 months ago

Same for me. claude running in ~/sandbox:

& sleep 5 && echo "Done!"
  ⎿  Cannot launch remote Claude Code session.

     Background tasks require a git repository. Initialize git or run from a git repository.

> is the repository initialized?

● Yes, the repository is initialized.

Though it does work if one tells claude that is should be a background task

> sleep 5 && echo "Done!"

● Would you like me to run this as a background task or as a normal (foreground) command?

  - Background: I'll launch it and you can continue working, then retrieve results later
  - Normal: I'll run it and wait for it to complete, showing you the output immediately

  Which would you prefer?

> background task

● Bash(sleep 5 && echo "Done!")
  ⎿  Running in the background (↓ to manage)

● Done! Your background task is running with ID: b68774a

  The command will sleep for 5 seconds and then print "Done!". You can:
  - Check the results now: I can retrieve them with the task ID
  - Continue working: Do something else and check later
  - Check status without blocking: I can check if it's done without waiting

  What would you like to do?

● Background command "Sleep for 5 seconds then print Done" completed (exit code 0).

● Task Output(non-blocking) b68774a
  ⎿  Done!

● Perfect! Your background task completed successfully. Here's the output:

  Done!

  What happened:
  - Task ID b68774a ran in the background
  - It slept for 5 seconds, then printed "Done!"
  - While it was running, you could continue doing other things
  - The system notified me when it finished
  - I retrieved the output and showed it to you

  That's how background tasks work! You can launch multiple tasks and work on other things while they run.

emssik · 7 months ago

Have this same problem ((CC 2.0.76)

I can work with this repo on the web claude code without issues, but I can't run background remote tasks from local claude code.

UPDATE:

Description

When trying to use & PROMPT to launch a remote Claude Code session, I receive the error:

Cannot launch remote Claude Code session. Background tasks require a git repository. Initialize git or run from a git repository.

Despite being in a valid git repository with a GitHub remote configured.

Environment

Claude Code version: 2.0.76
OS: macOS
Shell: zsh

Repository Configuration

$ git remote -v
origin	https://github.com/emssik/cc.kurs.web.git (fetch)
origin	https://github.com/emssik/cc.kurs.web.git (push)

The .git directory exists and git status works correctly.

Debug Logs
Running claude --debug shows the URL parsing failure:

[DEBUG] Git remote URL: https://github.com/emssik/cc.kurs.web.git
[DEBUG] Could not parse repository from: https://github.com/emssik/cc.kurs.web.git
[DEBUG] Parsed repository: null from URL: https://github.com/emssik/cc.kurs.web.git
[DEBUG] Not in a GitHub repository, skipping path mapping update

Attempted Fixes
❌ Removed .git suffix: https://github.com/emssik/cc.kurs.web
❌ Changed to SSH format: git@github.com:emssik/cc.kurs.web.git
All formats produce the same parsing error.

Expected Behavior
Claude Code should recognize standard GitHub remote URLs and allow launching remote sessions via & PROMPT.

Additional Context
Claude Code on the Web works correctly with the same repository
GitHub App is installed and configured
User is authenticated with Max subscription
claude doctor reports no issues

j9o · 7 months ago

Adding debug findings from a similar case (closed #16256 as duplicate):

Environment: Claude Code 2.0.76, macOS Darwin 25.1.0, private repo with standard HTTPS remote

Debug log shows the specific failure point:

[DEBUG] Checking GitHub app installation for j9o/relentless-execution
[DEBUG] checkGithubAppInstalled: Unexpected response status 200

The repo parsing works correctly:

[DEBUG] Git remote URL: https://github.com/j9o/relentless-execution.git
[DEBUG] Parsed repository: j9o/relentless-execution

But the GitHub app installation check receives HTTP 200 (success) and treats it as "unexpected", causing the failure.

Verified setup:

✅ Claude GitHub app installed with "All repositories" access
✅ .github/workflows/claude.yml exists
✅ ANTHROPIC_API_KEY secret configured
✅ git rev-parse --is-inside-work-tree returns true
✅ Standard HTTPS remote URL (not custom SSH alias)
✅ Removed orphaned npm installation
✅ Tested with symlink path (no spaces) - same result

The issue appears to be in checkGithubAppInstalled not handling a successful 200 response correctly.

j9o · 7 months ago

User impact clarification:

This bug blocks the core workflow of handing off local sessions to claude.ai/code using &. The intended use case is:

Run 5-10 Claude sessions in parallel on claude.ai/code alongside local sessions
Hand off local sessions to web using &
Use --teleport to switch between local and web
Start/monitor sessions from Claude iOS app

This is a major productivity workflow, not just a minor feature. The GitHub app check failing prevents any handoff to the cloud, completely blocking parallel web execution.

JPyke3 · 7 months ago

~I'm not sure if this helps anyone, but I was having this exact problem. GitHub app looked installed completely fine. GitHub actions were even in place and working. But I still got:~

& test prompt
  ⎿  Cannot launch remote Claude Code session.

     The Claude GitHub app must be installed on this repository first.
     https://github.com/apps/claude/installations/new

~I managed to resolve it by going to https://claude.ai/code, selecting the repo and sending a prompt (Can literally be anything). Once I did that once. It then allowed me to use &.~

Edit: I clearly had a different promblem to this thread. Just leaving this comment here in case anyone lands on it via first google result like I did

amorriscode contributor · 7 months ago

This should now be resolved. Sorry about that!

LA · 7 months ago

~I'm not sure if this helps anyone, but I was having this exact problem. GitHub app looked installed completely fine. GitHub actions were even in place and working. But I still got:~ `` & test prompt ⎿ Cannot launch remote Claude Code session. The Claude GitHub app must be installed on this repository first. https://github.com/apps/claude/installations/new ` ~I managed to resolve it by going to https://claude.ai/code, selecting the repo and sending a prompt (Can literally be anything). Once I did that once. It then allowed me to use &`.~ Edit: I clearly had a different promblem to this thread. Just leaving this comment here in case anyone lands on it via first google result like I did

Not to further hijack this thread, but your crossed out resolution is what worked for me as well for:

  ⎿  Cannot launch remote Claude Code session.

     The Claude GitHub app must be installed on this repository first.
     https://github.com/apps/claude/installations/new

There is a bug that can be worked around by starting a web session for the repo. And then a background task can be started for that repo. Thanks!

ericdfields · 7 months ago

I was getting this error and I had to do the above. I simply went to https://claude.ai/code and clicked on the repo name from the dropdown list. That's it. Then it worked.

emssik · 7 months ago

Not always 😿

https://github.com/anthropics/claude-code/issues/16831

github-actions[bot] · 7 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

[BUG] Background Tasks Fail to Detect Valid Git Repository

Preflight Checklist

What's Wrong?

Summary

Environment

Repository Information

Expected Behavior

Actual Behavior

Additional Context

Analysis

Suggested Investigation

Workaround

What Should Happen?

Error Messages/Logs

Steps to Reproduce

Steps to Reproduce

Validation Performed

✅ Git Repository Validation

✅ Permissions Check

✅ Path Check (No Symlinks)

✅ Git Config Check

Claude Model

Is this a regression?

Last Working Version

Claude Code Version

Platform

Operating System

Terminal/Shell

Additional Information

13 Comments

Description

Environment

Repository Configuration

Related Claude Code issues

Browse by topic