Jupiter Workspaces

Turn GitHub Issues, optional Jira tasks, and local custom tasks into isolated VS Code workspaces with task branches, AI context, pull requests, and GitHub Actions in one flow.

Jupiter is built for engineers who live in VS Code and need task-scoped worktrees. Pick a GitHub issue, a Jira task when Jira is configured, or create a local custom task, then Jupiter creates a dedicated git worktree, keeps every task in its own branch and workspace, and opens the right context when it is time to code, review, run CI, or create a pull request.

Why Teams Use Jupiter

GitHub Issues provide the default task queue. Jira can be added when the project uses it. Local custom tasks cover ad hoc work that has no external issue yet. Jupiter prepares the local workspace where that work can happen safely.

• Start several GitHub issues, Jira tasks, or local custom tasks without constantly switching one checkout back and forth.
• Keep each task in its own git worktree, branch, VS Code workspace, and saved session.
• Preserve SSH or HTTPS remotes from the source repository.
• Create a per-task agent context for OpenAI Codex IDE, OpenAI Codex CLI, or VS Code Chat / GitHub Copilot.
• Link a Telegram project forum and follow each Codex CLI task in its own Telegram topic.
• Review changed files, generate concise commit messages, commit, push, and open GitHub pull requests from the task view.
• Run and track selected GitHub Actions workflows for the task branch.
• Diagnose GitHub task access, optional Jira access, Git, remotes, and workspace configuration from one command.

Daily Workflow

1. Run Jupiter: Setup Wizard once for the repository.
2. Open the Jupiter Activity Bar view and refresh GitHub tasks.
3. Start a task from the tree, or run Jupiter: Create Custom Task for ad hoc local work.
4. Jupiter creates or reuses a task branch and opens an isolated worktree workspace.
5. Use Jupiter: Create Agent when you want a task-aware Codex IDE, Codex CLI, or Copilot agent.
6. Inspect task files, commit and push, run the selected task Action, and create a pull request.
7. Jupiter links Jira PRs back to Jira when the task came from Jira, and keeps every task session available until you remove it.

Screenshots

Tasks In VS Code

Group active sessions, GitHub issues, and configured Jira tasks by work state, filter the list, create local custom tasks, and start work without leaving the editor.

Task Details And Local State

See the branch, worktree path, PR state, Git notices, task Action state, and the next available task actions in one view.

Task-Aware Agent Context

Create a per-task agent with generated .jupiter/agent-context.md and .jupiter/codex-agent-prompt.md files, so Codex IDE, Codex CLI, or Copilot starts with the GitHub, Jira, or local custom task, branch, repository, and worktree context.

Core Features

• Task worktrees: create one local git worktree per GitHub issue, Jira task, or local custom task, under a configurable worktree root.
• Local custom tasks: start ad hoc work from a title, optional description, and a key like LOCAL-1 when no external issue exists yet.
• Branch naming: generate stable task branch names from task keys and summaries. GitHub issues use canonical keys like GH-123; local custom tasks default to LOCAL-N.
• Workspace profiles: save and switch named Jupiter configuration profiles for different repositories or teams.
• Agent handoff: create or reopen task agents through OpenAI Codex IDE, run headless Codex CLI agents, or use VS Code Chat / GitHub Copilot.
• Telegram project forum: with jupiter.ai.agentProvider=codexCli, link one Telegram supergroup with Topics enabled, then create one topic per active task for prompts, Codex CLI results, updates, and safe /jupiter commands.
• Task files: inspect branch and working tree changes, open editable diffs, and focus on the files that matter for the current task.
• Commit and push: use a Jupiter Git Files view with an editable suggested commit message and in-view Commit & Push control.
• Pull requests: push the task branch, create a GitHub PR, and write the PR link back to Jira only for Jira-sourced tasks.
• GitHub Actions: choose a workflow, dispatch it for the task branch, and track the latest run status from the task detail view.
• Diagnostics: verify GitHub sign-in, optional Jira credentials, git remotes, source paths, worktree root, and base branch setup.

Requirements

• VS Code 1.120 or newer.
• Git available in PATH.
• GitHub sign-in in VS Code with repository access.
• Jira Cloud email and API token only when the project uses Jira tasks.
• Optional Telegram bot token and a Telegram supergroup with Topics enabled when using the Codex CLI agent provider.
• OpenAI Codex extension for the default task-agent flow, OpenAI Codex CLI for Telegram-driven agents, or GitHub Copilot Chat for the alternative agent flow.
• A GitHub repository configured through Jupiter: Setup Wizard or detected from the current workspace origin remote.

Setup

1. Install Jupiter Workspaces.
2. Open the repository Jupiter should use as the base checkout for task worktrees.
3. Run Jupiter: Setup Wizard.
4. Enter the GitHub repository, base branch, local repo for task worktrees, worktree root, PR mode, and AI settings.
5. Choose Configure Jira now or Skip Jira for now. Skipping Jira leaves any existing Jira settings and secrets untouched.
6. Open the Jupiter Activity Bar view and run Refresh GitHub Tasks.
7. Start a GitHub issue from the tree or with Jupiter: Start Task. Jira tasks appear after jupiter.jira.baseUrl and Jira credentials are configured. Use Jupiter: Create Custom Task when the work has no GitHub or Jira issue.

Jupiter writes non-secret settings to the current VS Code workspace, not User Settings. Jira credentials stay in VS Code SecretStorage when Jira is configured.

For Telegram, create a supergroup, enable Topics, add the Jupiter bot as an admin with permission to send messages and manage topics, then run Jupiter: Configure Telegram Bot and Jupiter: Link Telegram Project.

Run Jupiter: Run Diagnostics if tasks do not load, worktree creation fails, GitHub actions are missing, or a PR cannot be created.

Commands

• Jupiter: Setup Wizard: configure GitHub, the local repo used for task worktrees, worktree root, PR mode, AI settings, and optional Jira.
• Jupiter: Show Workspace Dashboard: inspect active task source, Git, GitHub, optional Jira, and workspace profile settings.
• Jupiter: Save Workspace Profile / Jupiter: Switch Workspace Profile: manage named jupiter.* setting groups.
• Jupiter: Refresh Tasks: reload all available task sources and active task sessions.
• Jupiter: Refresh GitHub Tasks: reload GitHub issues from the configured repository.
• Jupiter: Refresh Jira Tasks: reload Jira tasks when Jira is configured.
• Jupiter: Start Task: use or create a task branch and isolated git worktree.
• Jupiter: Create Custom Task: create a local Jupiter task and start its isolated branch and worktree.
• Jupiter: Start Task With Branch: choose an existing branch or enter a custom branch name.
• Jupiter: Start Task From Branch: create a fresh task branch from a selected base branch.
• Jupiter: Open Worktree: open the task worktree in the current VS Code window.
• Jupiter: Change Task Branch: move an active task session to another existing branch, switching the task worktree when it is clean or linking an already checked-out worktree.
• Jupiter: Create Agent: create a per-task Codex or Copilot agent with generated Jupiter context files.
• Jupiter: Open Agent: reopen the configured agent surface for a task that already has an agent.
• Jupiter: Show Task Files: inspect files changed by the task branch and working tree.
• Jupiter: Commit & Push Task: commit selected task changes and push the task branch.
• Jupiter: Open Task Source Control: open the task worktree and focus Source Control, or Jupiter Git Files when VS Code Git is disabled.
• Jupiter: Select Task Action: choose the GitHub Actions workflow used for the task branch.
• Jupiter: Run Task Action: push the task branch and dispatch the selected GitHub Actions workflow.
• Jupiter: Refresh Task Action Status: refresh the latest tracked task Action run.
• Jupiter: Create Pull Request: push the task branch, create a GitHub PR, and link it to Jira only for Jira tasks.
• Jupiter: Configure Telegram Bot: save and verify a Telegram bot token in VS Code SecretStorage.
• Jupiter: Link Telegram Project: bind the current project to a Telegram supergroup/forum.
• Jupiter: Create Telegram Topic For Task: create and link a Telegram forum topic for an active task.
• Jupiter: Send Telegram Task Update: send the current task state to its Telegram topic.
• Jupiter: Open Telegram Topic / Jupiter: Unlink Telegram Topic: manage the task's Telegram topic binding.
• Jupiter: Cancel Task: remove the task from Jupiter's active list without changing the source task, local worktree, or local branch.
• Jupiter: Open Task Source: open the source issue in GitHub or Jira. Local custom tasks show that no external source URL exists.
• Jupiter: Run Diagnostics: check GitHub auth, optional Jira, Git, settings, and workspace remote setup.

Active task sessions, the active task marker, and saved workspace profiles are stored per project in .jupiter/state.json. Jupiter adds that file to the repository's local .git/info/exclude when possible, so the state stays on the machine without polluting commits. Generated Jupiter task workspaces inherit the same project state path, so task windows still see their source task while unrelated project folders stay isolated.

Settings

• jupiter.ai.agentProvider: Agent integration for per-task agents. Use codex for the OpenAI Codex IDE extension, codexCli for headless Codex CLI agents with Telegram prompts/results, or copilotChat for VS Code Chat / GitHub Copilot.
• jupiter.ai.codexOpenTarget: Where new Codex task agents are created. Use sidebar for the right Codex sidebar or editor for a main editor tab.
• jupiter.ai.copilotModelId: Copilot model id for branch names and commit summaries. Leave empty to auto-select the cheapest available model.
• jupiter.jira.baseUrl: Optional Jira Cloud base URL.
• jupiter.jira.jql: JQL used to load task list.
• jupiter.jira.maxResults: Maximum Jira tasks to load across enhanced JQL search pages.
• jupiter.github.owner: GitHub owner or organization.
• jupiter.github.repo: GitHub repository name.
• jupiter.github.baseBranch: Base branch for worktrees and PRs.
• jupiter.github.draftPr: Create PRs as draft by default.
• jupiter.github.issueQuery: GitHub issue search query. Jupiter automatically adds repo:owner/repo.
• jupiter.git.branchPrefix: Branch prefix, default feature.
• jupiter.git.disableVsCodeGitInWorktrees: Disable built-in VS Code Git in generated task worktree workspaces, preventing automatic Git scans. Enabled by default.
• jupiter.git.remoteUrl: Optional SSH/HTTPS git remote URL used for source clones.
• jupiter.git.sshKeyPath: Optional SSH private key path used for Git clone, fetch, and push operations.
• jupiter.git.sourcePath: Optional local checkout Jupiter uses as the base when creating task worktrees. Leave empty to let Jupiter clone the configured GitHub repository automatically.
• jupiter.git.worktreeRoot: Folder where task worktrees are created.
• jupiter.pr.titleTemplate: PR title template.
• jupiter.pr.bodyTemplate: PR body template.
• jupiter.telegram.enabled: Enable Telegram bot polling for linked project forums. Supported only when jupiter.ai.agentProvider is codexCli.
• jupiter.telegram.autoCreateTopics: Automatically create a Telegram topic when Jupiter sends the first Telegram update for a task.

Telegram Commands

Telegram is supported only with jupiter.ai.agentProvider=codexCli. Inside a linked task topic, send a normal message to run the task's Codex CLI agent and receive the final agent result back in the same topic. Jupiter also accepts safe commands:

• /jupiter status
• /jupiter summary
• /jupiter files
• /jupiter action
• /jupiter pr
• /jupiter update
• /jupiter help

Add a task key, such as /jupiter status GH-123, to address another task topic linked in the same Telegram project.

Troubleshooting

Run Jupiter: Run Diagnostics first. It prints a structured report to the Jupiter output channel with the configured version, GitHub repository, GitHub issue query, optional Jira URL, Telegram status, JQL limit, git remote URL, base branch, source path, worktree root, Git availability, Jira credential check, GitHub sign-in state, and detected workspace origin.

If GitHub tasks do not load, verify jupiter.github.owner, jupiter.github.repo, jupiter.github.issueQuery, and GitHub sign-in access. If Jira tasks do not load, verify that jupiter.jira.baseUrl points to your Jira Cloud tenant and that the saved API token belongs to the same Atlassian account.

If worktree creation fails, verify local Git authentication for the configured remote URL. Jupiter preserves SSH remotes when it detects them, so your normal SSH key setup should continue to work.

Known Limitations

• Jupiter currently targets GitHub Issues for the primary task queue, Jira Cloud for optional Jira task queues, local custom tasks for ad hoc work, Telegram supergroup forum topics for task updates, and GitHub pull requests.
• Telegram folder/group/channel creation is not automated; Jupiter uses a user-created supergroup with Topics enabled.
• Some Jira transition automation and multi-repository workflows are still evolving.