[{"data":1,"prerenderedAt":12612},["ShallowReactive",2],{"docs-\u002Fdocs\u002Frequirements":3,"docs-nav":286},{"id":4,"title":5,"body":6,"description":276,"extension":277,"group":278,"icon":279,"meta":280,"navTitle":5,"navigation":281,"order":271,"path":282,"seo":283,"stem":284,"__hash__":285},"docs\u002Fdocs\u002Frequirements.md","Requirements",{"type":7,"value":8,"toc":265},"minimark",[9,13,18,26,36,46,67,95,104,109,116,124,133,137,143,147,174,178,185,189,258],[10,11,12],"p",{},"Plexus drives the Claude Code CLI on top of Git, so both must be on your machine — a couple of optional tools unlock the rest.",[14,15,17],"h2",{"id":16},"claude-code-cli","Claude Code CLI",[10,19,20,21,25],{},"Plexus runs every session through the Claude Code CLI; it does not bundle its own agent. Install Claude Code and confirm the ",[22,23,24],"code",{},"claude"," command works in a terminal:",[27,28,34],"pre",{"className":29,"code":31,"language":32,"meta":33},[30],"language-bash","claude --help\n","bash","",[22,35,31],{"__ignoreMap":33},[10,37,38,39,41,42,45],{},"Plexus finds ",[22,40,24],{}," on your ",[22,43,44],{},"PATH"," at startup, so a standard install needs no configuration. There's no API key to enter — your existing Claude Code authentication is handed through to each session.",[47,48,49],"callout",{},[10,50,51,59,60,62,63,66],{},[52,53,54,55,58],"strong",{},"The npm shim (",[22,56,57],{},"claude.cmd",") and Volta are fully supported on Windows, AI features included."," Sessions, AI diff review, AI pull request descriptions, session summaries and the review-and-fix cycle all run on those the same as on a native install. One caveat: if the path to ",[22,61,24],{}," contains one of ",[22,64,65],{},"& | \u003C > ^ % \"",", Plexus refuses it rather than hand it to the Windows command prompt — move it, or use the native install below.",[47,68,70],{"tone":69},"warn",[10,71,72,73,75,76,79,80,82,83,85,86,89,90,94],{},"If Plexus can't find ",[22,74,24],{}," — you'll see a message saying the agent isn't installed — set an explicit path in ",[52,77,78],{},"Settings → Advanced → Path to the Claude program"," and point it at the actual program file. This is common on Windows, where Claude Code installs as an npm shim (",[22,81,57],{},") or through Volta and isn't on the ",[22,84,44],{}," Plexus sees — for example ",[22,87,88],{},"C:\\Users\\me\\AppData\\Roaming\\npm\\claude.cmd",". It's about ",[91,92,93],"em",{},"finding"," Claude Code — you don't need it to make an individual feature work.",[10,96,97,98,103],{},"See ",[99,100,102],"a",{"href":101},"\u002Fdocs\u002Fsettings","Settings"," for where this lives.",[105,106,108],"h3",{"id":107},"prefer-the-native-install","Prefer the native install?",[10,110,111,112,115],{},"Nothing in Plexus requires it, but Claude Code also ships a standalone build that doesn't depend on Node or npm. Run ",[22,113,114],{},"claude install"," from a terminal to switch an existing install over, or on Windows run this in PowerShell:",[27,117,122],{"className":118,"code":120,"language":121,"meta":33},[119],"language-powershell","irm https:\u002F\u002Fclaude.ai\u002Finstall.ps1 | iex\n","powershell",[22,123,120],{"__ignoreMap":33},[10,125,126,127,132],{},"Anthropic's setup guide is at ",[99,128,129],{"href":129,"rel":130},"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fsetup",[131],"nofollow",".",[14,134,136],{"id":135},"git","Git",[10,138,139,140,142],{},"Git must be installed and on your ",[22,141,44],{},". Plexus uses it to detect repositories, create and remove worktrees, switch branches, and compute diffs. Any standard Git install satisfies this.",[14,144,146],{"id":145},"git-providers-for-pull-requests","Git providers (for pull requests)",[10,148,149,150,153,154,157,158,161,162,165,166,169,170,132],{},"Pull-request features — opening PRs, reading status, and checking CI — need a connected git provider, either ",[52,151,152],{},"GitHub or Bitbucket",". There's nothing to install: open ",[52,155,156],{},"Settings → Git providers"," and click ",[52,159,160],{},"Connect",", then approve the one-click sign-in in your browser. The ",[22,163,164],{},"gh"," CLI is ",[52,167,168],{},"not"," required. Everything else (sessions, editing, local Git) works without connecting. See ",[99,171,173],{"href":172},"\u002Fdocs\u002Fconnections","Connections",[14,175,177],{"id":176},"notify-send-linux-optional","notify-send (Linux, optional)",[10,179,180,181,184],{},"On Linux, Plexus uses ",[22,182,183],{},"notify-send"," for native desktop notifications — for instance when an agent needs your input. Without it, Plexus falls back to its in-app notifications, so it's purely optional. macOS and Windows use their native notification systems and need nothing extra.",[14,186,188],{"id":187},"supported-platforms","Supported platforms",[190,191,192,208],"table",{},[193,194,195],"thead",{},[196,197,198,202,205],"tr",{},[199,200,201],"th",{},"OS",[199,203,204],{},"Architectures",[199,206,207],{},"Notes",[209,210,211,223,241],"tbody",{},[196,212,213,217,220],{},[214,215,216],"td",{},"macOS",[214,218,219],{},"Apple Silicon (aarch64), Intel (x86_64)",[214,221,222],{},"Native builds for both",[196,224,225,228,231],{},[214,226,227],{},"Linux",[214,229,230],{},"x86_64",[214,232,233,234,237,238,240],{},"AppImage and ",[22,235,236],{},".deb","; ",[22,239,183],{}," optional",[196,242,243,246,248],{},[214,244,245],{},"Windows",[214,247,230],{},[214,249,250,253,254,257],{},[22,251,252],{},"-setup.exe"," (per-user, recommended) or ",[22,255,256],{},".msi"," (per-machine); npm, Volta and native Claude Code installs all fully supported",[10,259,260,261,132],{},"Ready to get it running? See ",[99,262,264],{"href":263},"\u002Fdocs\u002Finstall","Install",{"title":33,"searchDepth":266,"depth":266,"links":267},2,[268,272,273,274,275],{"id":16,"depth":266,"text":17,"children":269},[270],{"id":107,"depth":271,"text":108},3,{"id":135,"depth":266,"text":136},{"id":145,"depth":266,"text":146},{"id":176,"depth":266,"text":177},{"id":187,"depth":266,"text":188},"What you need installed for Plexus and its features.","md","Overview","Check",{},true,"\u002Fdocs\u002Frequirements",{"title":5,"description":276},"docs\u002Frequirements","m7-5j8xV6VEVg8xVHYvvGLeTXL6ndt5KRSeuHnI2U1s",[287,445,876,1037,1499,1802,2046,2379,4053,4219,5026,5548,5765,6098,7324,7796,8065,8324,9053,9781,9921,10300,12205,12404],{"id":288,"title":289,"body":290,"description":437,"extension":277,"group":278,"icon":438,"meta":439,"navTitle":289,"navigation":281,"order":440,"path":441,"seo":442,"stem":443,"__hash__":444},"docs\u002Fdocs\u002Findex.md","Introduction",{"type":7,"value":291,"toc":432},[292,295,299,314,326,330,404,409,413],[10,293,294],{},"Plexus is a fast, native, local desktop control plane for running coding-agent CLIs — Claude Code — in parallel, without juggling a dozen terminal tabs.",[14,296,298],{"id":297},"the-core-idea","The core idea",[10,300,301,302,305,306,309,310,313],{},"You add a git repository as a ",[52,303,304],{},"Project"," (Projects live inside ",[52,307,308],{},"Workspaces","), then spin up ",[52,311,312],{},"Sessions",". Each Session is its own git worktree — on a fresh branch Plexus cuts for it, or on a branch that already exists — wrapping a named Claude Code session in a real terminal. Several agents run side by side, each isolated in its own worktree, so their changes never collide — and you always know at a glance which one is working and which is waiting for you.",[10,315,316,317,320,321,325],{},"The shape of it: ",[52,318,319],{},"Workspace ▸ Project ▸ Session",". See ",[99,322,324],{"href":323},"\u002Fdocs\u002Fconcepts","Concepts"," for the model in depth.",[14,327,329],{"id":328},"what-you-get","What you get",[331,332,333,340,350,360,380,390,398],"ul",{},[334,335,336,339],"li",{},[52,337,338],{},"Parallel, isolated sessions."," Every Session lives in its own worktree, so multiple agents work on different features at once without stepping on each other or your main checkout.",[334,341,342,345,346,132],{},[52,343,344],{},"Always know the state."," A live status dot tells you which sessions are actively working versus waiting for input, alongside each session's branch and pull-request state — see ",[99,347,349],{"href":348},"\u002Fdocs\u002Fstatus","Status",[334,351,352,355,356,132],{},[52,353,354],{},"PR-style review."," Read changes as a unified diff and leave inline comments the agent reads and iterates on, all inside the app — see ",[99,357,359],{"href":358},"\u002Fdocs\u002Freview","Review",[334,361,362,365,366,370,371,375,376,132],{},[52,363,364],{},"Built-in editor and git client."," Browse and edit files in the worktree, then stage, commit, and manage branches without switching tools — from a per-session ",[99,367,369],{"href":368},"\u002Fdocs\u002Fgit","Git tab"," up to a full ",[99,372,374],{"href":373},"\u002Fdocs\u002Fproject-git","project-level git client"," with a commit graph and conflict resolution. See also ",[99,377,379],{"href":378},"\u002Fdocs\u002Fexplorer","Explorer",[334,381,382,385,386,132],{},[52,383,384],{},"Three-level lifecycle hooks."," Run your own commands at the global, workspace, and project levels to automate setup, checks, and teardown — see ",[99,387,389],{"href":388},"\u002Fdocs\u002Fhooks","Hooks",[334,391,392,395,396,132],{},[52,393,394],{},"Layered settings."," Configuration cascades from global defaults down to per-project and per-session overrides, so each repo behaves the way it needs to — see ",[99,397,102],{"href":101},[334,399,400,403],{},[52,401,402],{},"Native, local, and fast."," Plexus is a real desktop app that runs on your machine — it never sends your code or credentials anywhere.",[47,405,406],{},[10,407,408],{},"Plexus drives the Claude Code CLI directly, so you keep your existing agent setup, plan, and configuration.",[14,410,412],{"id":411},"where-to-next","Where to next",[331,414,415,420,427],{},[334,416,417,419],{},[99,418,264],{"href":263}," — download a signed build and let it auto-update.",[334,421,422,426],{},[99,423,425],{"href":424},"\u002Fdocs\u002Fgetting-started","Getting started"," — add a repository and run your first session.",[334,428,429,431],{},[99,430,324],{"href":323}," — Workspaces, Projects, Sessions, and worktrees explained.",{"title":33,"searchDepth":266,"depth":266,"links":433},[434,435,436],{"id":297,"depth":266,"text":298},{"id":328,"depth":266,"text":329},{"id":411,"depth":266,"text":412},"What Plexus is and the problem it solves.","BookOpen",{},1,"\u002Fdocs",{"title":289,"description":437},"docs\u002Findex","bE6y6npxdm1C_VN0C65C6RygFLvA-ks65sQo9hOFhgQ",{"id":446,"title":447,"body":448,"description":871,"extension":277,"group":278,"icon":476,"meta":872,"navTitle":264,"navigation":281,"order":266,"path":263,"seo":873,"stem":874,"__hash__":875},"docs\u002Fdocs\u002Finstall.md","Installation",{"type":7,"value":449,"toc":863},[450,453,457,460,473,477,480,488,503,506,509,542,556,559,569,602,608,614,617,623,635,638,641,663,669,704,708,714,720,735,738,741,802,808,842,857],[10,451,452],{},"Plexus ships as a native desktop app — download the build for your platform, install it like any other native app, and it keeps itself current after that.",[454,455],"download-button",{"size":456},"lg",[10,458,459],{},"The button picks the right build for your OS automatically; use the platform menu on it to choose another. Prefer to pick by hand? Every asset is listed below.",[47,461,462],{},[10,463,464,465,468,469,132],{},"The download button routes through a lightweight redirect that counts an ",[52,466,467],{},"anonymous"," total-download tally before forwarding you to the file on GitHub — no account, no personal data, no cookies. See our ",[99,470,472],{"href":471},"\u002Flegal\u002Fprivacy","Privacy Policy",[14,474,476],{"id":475},"download","Download",[10,478,479],{},"Every installer lives on the public releases page:",[27,481,486],{"className":482,"code":484,"language":485},[483],"language-text","https:\u002F\u002Fgithub.com\u002FCodedWords\u002Fplexus-releases\u002Freleases\n","text",[22,487,484],{"__ignoreMap":33},[10,489,490,491,494,495,498,499,502],{},"Open the ",[52,492,493],{},"latest"," release and grab the asset that matches your platform from the sections below. Filenames carry the version (shown here as ",[22,496,497],{},"\u003Cversion>",", e.g. ",[22,500,501],{},"0.1.0",").",[14,504,216],{"id":505},"macos",[10,507,508],{},"Plexus publishes separate builds for Apple Silicon and Intel — pick the one that matches your Mac.",[190,510,511,520],{},[193,512,513],{},[196,514,515,518],{},[199,516,517],{},"Mac",[199,519,476],{},[209,521,522,532],{},[196,523,524,527],{},[214,525,526],{},"Apple Silicon (M1 and later)",[214,528,529],{},[22,530,531],{},"Plexus_\u003Cversion>_aarch64.dmg",[196,533,534,537],{},[214,535,536],{},"Intel",[214,538,539],{},[22,540,541],{},"Plexus_\u003Cversion>_x64.dmg",[10,543,490,544,547,548,551,552,555],{},[22,545,546],{},".dmg",", drag ",[52,549,550],{},"Plexus"," into ",[22,553,554],{},"Applications",", then launch it from there.",[14,557,227],{"id":558},"linux",[10,560,561,562,564,565,568],{},"Linux builds are x86_64 (amd64) only, in two formats. The ",[22,563,236],{}," suits Debian\u002FUbuntu-based distros; the ",[22,566,567],{},".AppImage"," is a portable single-file binary that runs anywhere.",[190,570,571,580],{},[193,572,573],{},[196,574,575,578],{},[199,576,577],{},"Format",[199,579,476],{},[209,581,582,592],{},[196,583,584,587],{},[214,585,586],{},"Debian\u002FUbuntu package",[214,588,589],{},[22,590,591],{},"Plexus_\u003Cversion>_amd64.deb",[196,593,594,597],{},[214,595,596],{},"Portable AppImage",[214,598,599],{},[22,600,601],{},"Plexus_\u003Cversion>_amd64.AppImage",[10,603,604,605,607],{},"Install the ",[22,606,236],{},":",[27,609,612],{"className":610,"code":611,"language":32,"meta":33},[30],"sudo apt install .\u002FPlexus_\u003Cversion>_amd64.deb\n",[22,613,611],{"__ignoreMap":33},[10,615,616],{},"Or run the AppImage directly:",[27,618,621],{"className":619,"code":620,"language":32,"meta":33},[30],"chmod +x Plexus_\u003Cversion>_amd64.AppImage\n.\u002FPlexus_\u003Cversion>_amd64.AppImage\n",[22,622,620],{"__ignoreMap":33},[47,624,625],{},[10,626,627,628,630,631,634],{},"For desktop notifications on Linux, install ",[22,629,183],{}," (",[22,632,633],{},"libnotify-bin"," on Debian\u002FUbuntu). It's optional — Plexus runs fine without it.",[14,636,245],{"id":637},"windows",[10,639,640],{},"Windows builds are x64 only.",[190,642,643,651],{},[193,644,645],{},[196,646,647,649],{},[199,648,577],{},[199,650,476],{},[209,652,653],{},[196,654,655,658],{},[214,656,657],{},"Installer",[214,659,660],{},[22,661,662],{},"Plexus_\u003Cversion>_x64-setup.exe",[10,664,665,666,668],{},"Run the ",[22,667,252],{}," and follow the prompts. It installs for the current user, so you don't need administrator rights, and Plexus is added to the Start menu when it finishes.",[47,670,671],{},[10,672,673,674,676,677,682,683,685,686,688,689,691,692,695,696,699,700,132],{},"An ",[22,675,256],{}," is also published on the ",[99,678,681],{"href":679,"rel":680},"https:\u002F\u002Fgithub.com\u002FCodedWords\u002Fplexus-releases\u002Freleases",[131],"releases page",", for per-machine and managed deployments. Both formats keep themselves up to date with a matching package, so an existing ",[22,684,256],{}," install needs no action — it upgrades in place, asking for administrator approval each time, because that's what a per-machine install requires. If you do reinstall it by hand, take the ",[22,687,256],{}," from the releases page: the download button on this site always hands out the ",[22,690,252],{},", which is a ",[91,693,694],{},"different",", per-user install rather than an upgrade of the one you have. If you'd rather switch to the per-user installer, that's exactly what to run — but Windows asks once to remove the MSI version first, and you should ",[52,697,698],{},"accept that prompt",". Declining it doesn't stop the new install, it just leaves the old registration behind, and Windows then asks the same question on every future update. If that already happened, Plexus offers to clear it up — see ",[99,701,703],{"href":702},"#staying-up-to-date","Staying up to date",[14,705,707],{"id":706},"verify-prerequisites","Verify prerequisites",[10,709,710,711,713],{},"Plexus drives the Claude Code CLI and Git, so both must be installed and on your ",[22,712,44],{},". After installing, confirm them from a terminal:",[27,715,718],{"className":716,"code":717,"language":32,"meta":33},[30],"claude --help\ngit --version\n",[22,719,717],{"__ignoreMap":33},[10,721,722,723,725,726,728,729,732,733,132],{},"If ",[22,724,24],{}," isn't found, ",[99,727,5],{"href":282}," explains how Plexus locates it and the ",[52,730,731],{},"Path to the Claude program"," override. For pull-request features you connect a git provider (GitHub or Bitbucket) inside the app — no extra CLI to install. See ",[99,734,173],{"href":172},[14,736,703],{"id":737},"staying-up-to-date",[10,739,740],{},"Plexus updates itself — you don't need to revisit the releases page for future versions.",[331,742,743,750,761,767,770,773,787],{},[334,744,745,746,749],{},"It checks for a new release on launch ",[52,747,748],{},"and every ~30 minutes"," while it's open.",[334,751,752,753,756,757,760],{},"When one is available, you get a one-click ",[52,754,755],{},"Install & restart",", or ",[52,758,759],{},"Install when idle"," — which applies the update automatically once all your sessions finish, so a running agent is never interrupted. It waits for a short countdown (which you can cancel) before restarting.",[334,762,763,764,132],{},"You can also check on demand from ",[52,765,766],{},"Settings → About → Check for updates",[334,768,769],{},"You're prompted once per new version — no repeated nagging.",[334,771,772],{},"Every update is signature-verified before it's applied, so a tampered build won't install.",[334,774,775,776,778,779,781,782,784,785,132],{},"Updates arrive in the format you installed — an ",[22,777,256],{}," install updates with an ",[22,780,256],{},", the ",[22,783,252],{}," with a ",[22,786,252],{},[334,788,789,790,793,794,798,799,132],{},"After an update, a ",[52,791,792],{},"What's new"," window shows what changed the first time you run the new version — once per version, with the release's changes listed down the left-hand side, one per feature. If you skipped several releases, they're all selectable at the top of the window; if you're coming from a version older than the window itself, you get the notes for the release you landed on and the rest are on the ",[99,795,797],{"href":796},"\u002Fchangelog","Changelog"," page. A brand-new install opens straight into Plexus instead. You can reopen the window any time from ",[52,800,801],{},"Settings → About → What's new",[10,803,804,805,807],{},"The same release notes are published on the ",[99,806,797],{"href":796}," page, newest first — handy for reading what's coming before you update, or catching up on a release you clicked past.",[47,809,810],{},[10,811,812,815,816,818,819,821,822,825,826,829,830,833,834,837,838,841],{},[52,813,814],{},"Windows: \"An older Plexus installation is still registered\"?"," Earlier versions could update an ",[22,817,256],{}," install onto the ",[22,820,252],{}," one, leaving the older per-machine install registered behind — which is what makes Windows ask ",[91,823,824],{},"\"Are you sure you want to uninstall this product?\""," during an update. If Plexus finds that leftover it offers to remove it: choose ",[52,827,828],{},"Remove it"," and confirm the Windows permission prompt. That uninstalls the old per-machine copy (the one under ",[22,831,832],{},"C:\\Program Files\\Plexus",", along with its Start-menu shortcut) and the question stops for good. The Plexus you're running is a different, per-user install and stays exactly where it is, and your settings, projects and sessions aren't stored in either install folder — they're untouched. If Windows takes longer than expected to finish, Plexus offers ",[52,835,836],{},"Check again"," instead of asking you to repeat the removal. The offer also lives in ",[52,839,840],{},"Settings → About"," until it's done.",[47,843,844],{},[10,845,846,847,850,851,853,854,856],{},"Need to reinstall or roll back manually? Download the installer for any version from the ",[99,848,681],{"href":679,"rel":849},[131]," and run it over your existing install. Use the same format you originally installed (on Windows, ",[22,852,252],{}," or ",[22,855,256],{},") so it upgrades in place.",[10,858,859,860,862],{},"Installed? Head to ",[99,861,425],{"href":424}," to add a repository and run your first session.",{"title":33,"searchDepth":266,"depth":266,"links":864},[865,866,867,868,869,870],{"id":475,"depth":266,"text":476},{"id":505,"depth":266,"text":216},{"id":558,"depth":266,"text":227},{"id":637,"depth":266,"text":245},{"id":706,"depth":266,"text":707},{"id":737,"depth":266,"text":703},"Download and install Plexus on macOS, Linux, or Windows.",{},{"title":447,"description":871},"docs\u002Finstall","rTIXbT0LXnaOcBXfh_B-GUeJuJl5tSGy4nrtdRqR2rA",{"id":4,"title":5,"body":877,"description":276,"extension":277,"group":278,"icon":279,"meta":1035,"navTitle":5,"navigation":281,"order":271,"path":282,"seo":1036,"stem":284,"__hash__":285},{"type":7,"value":878,"toc":1026},[879,881,883,887,892,898,910,926,930,932,936,941,946,948,952,954,968,970,974,976,1022],[10,880,12],{},[14,882,17],{"id":16},[10,884,20,885,25],{},[22,886,24],{},[27,888,890],{"className":889,"code":31,"language":32,"meta":33},[30],[22,891,31],{"__ignoreMap":33},[10,893,38,894,41,896,45],{},[22,895,24],{},[22,897,44],{},[47,899,900],{},[10,901,902,59,906,62,908,66],{},[52,903,54,904,58],{},[22,905,57],{},[22,907,24],{},[22,909,65],{},[47,911,912],{"tone":69},[10,913,72,914,75,916,79,918,82,920,85,922,89,924,94],{},[22,915,24],{},[52,917,78],{},[22,919,57],{},[22,921,44],{},[22,923,88],{},[91,925,93],{},[10,927,97,928,103],{},[99,929,102],{"href":101},[105,931,108],{"id":107},[10,933,111,934,115],{},[22,935,114],{},[27,937,939],{"className":938,"code":120,"language":121,"meta":33},[119],[22,940,120],{"__ignoreMap":33},[10,942,126,943,132],{},[99,944,129],{"href":129,"rel":945},[131],[14,947,136],{"id":135},[10,949,139,950,142],{},[22,951,44],{},[14,953,146],{"id":145},[10,955,149,956,153,958,157,960,161,962,165,964,169,966,132],{},[52,957,152],{},[52,959,156],{},[52,961,160],{},[22,963,164],{},[52,965,168],{},[99,967,173],{"href":172},[14,969,177],{"id":176},[10,971,180,972,184],{},[22,973,183],{},[14,975,188],{"id":187},[190,977,978,988],{},[193,979,980],{},[196,981,982,984,986],{},[199,983,201],{},[199,985,204],{},[199,987,207],{},[209,989,990,998,1010],{},[196,991,992,994,996],{},[214,993,216],{},[214,995,219],{},[214,997,222],{},[196,999,1000,1002,1004],{},[214,1001,227],{},[214,1003,230],{},[214,1005,233,1006,237,1008,240],{},[22,1007,236],{},[22,1009,183],{},[196,1011,1012,1014,1016],{},[214,1013,245],{},[214,1015,230],{},[214,1017,1018,253,1020,257],{},[22,1019,252],{},[22,1021,256],{},[10,1023,260,1024,132],{},[99,1025,264],{"href":263},{"title":33,"searchDepth":266,"depth":266,"links":1027},[1028,1031,1032,1033,1034],{"id":16,"depth":266,"text":17,"children":1029},[1030],{"id":107,"depth":271,"text":108},{"id":135,"depth":266,"text":136},{"id":145,"depth":266,"text":146},{"id":176,"depth":266,"text":177},{"id":187,"depth":266,"text":188},{},{"title":5,"description":276},{"id":1038,"title":425,"body":1039,"description":1492,"extension":277,"group":278,"icon":1493,"meta":1494,"navTitle":425,"navigation":281,"order":1495,"path":424,"seo":1496,"stem":1497,"__hash__":1498},"docs\u002Fdocs\u002Fgetting-started.md",{"type":7,"value":1040,"toc":1479},[1041,1044,1058,1062,1071,1075,1093,1103,1106,1110,1113,1145,1148,1152,1158,1188,1191,1195,1205,1221,1230,1238,1241,1245,1251,1286,1294,1298,1309,1325,1329,1332,1352,1364,1368,1372,1375,1425,1442,1446],[10,1042,1043],{},"Add a repository, create a session, and watch Claude Code go to work — your first run, end to end.",[10,1045,1046,1047,1049,1050,1052,1053,1055,1056,132],{},"This walkthrough assumes Plexus is already installed and that the Claude Code CLI and ",[22,1048,135],{}," are on your ",[22,1051,44],{},". If not, start with ",[99,1054,264],{"href":263}," and ",[99,1057,5],{"href":282},[14,1059,1061],{"id":1060},"launch-plexus","Launch Plexus",[10,1063,1064,1065,1068,1069,132],{},"Open the app. The left sidebar already holds a ",[52,1066,1067],{},"Default"," workspace, so you're never staring at an empty tree. A workspace is just a grouping for related repositories — rename it or add more whenever you like. For the full hierarchy behind workspaces, projects, and sessions, see ",[99,1070,324],{"href":323},[14,1072,1074],{"id":1073},"add-a-repository","Add a repository",[10,1076,1077,1078,1080,1081,1084,1085,1088,1089,1092],{},"A project is a single git repository. Hover the ",[52,1079,1067],{}," workspace row, open its ",[52,1082,1083],{},"⋯"," menu, and choose ",[52,1086,1087],{},"Add repository…",". (An empty workspace also shows an inline ",[52,1090,1091],{},"+ Add repository"," button.)",[10,1094,1095],{},[1096,1097],"img",{"alt":1098,"height":1099,"src":1100,"title":1101,"width":1102},"The Add repository button on the Default workspace row",248,"\u002Fdocs\u002Fgetting-started\u002Fadd-repository-button.png","Start from the Default workspace's Add repository button.",431,[10,1104,1105],{},"The dialog offers three ways to add a repository — pick whichever fits:",[105,1107,1109],{"id":1108},"from-a-local-folder","From a local folder",[10,1111,1112],{},"Point Plexus at a git repository already on your machine.",[1114,1115,1116,1133],"ol",{},[334,1117,1118,1119,1122,1123,1126],{},"Pick a folder in the native picker. If the folder isn't a git repository, Plexus offers to run ",[22,1120,1121],{},"git init"," for you.",[1124,1125],"br",{},[1096,1127],{"alt":1128,"height":1129,"src":1130,"title":1131,"width":1132},"The Add a repository dialog with a Choose folder button",240,"\u002Fdocs\u002Fgetting-started\u002Fadd-repository-choose-folder.png","Choose the repository folder on disk.",461,[334,1134,1135,1136,1138],{},"Enter a project name and confirm.",[1124,1137],{},[1096,1139],{"alt":1140,"height":1141,"src":1142,"title":1143,"width":1144},"The Add a repository dialog showing the repository folder and project name fields",320,"\u002Fdocs\u002Fgetting-started\u002Fadd-repository-details.png","Name the project, then Add project.",494,[10,1146,1147],{},"The folder on disk is never moved or modified — Plexus just points at it.",[105,1149,1151],{"id":1150},"from-a-connected-provider","From a connected provider",[10,1153,1154,1155,1157],{},"If you've connected GitHub or Bitbucket under ",[99,1156,156],{"href":172},", search your repositories and clone the one you want — no URL to copy.",[1114,1159,1160,1170,1181],{},[334,1161,1162,1163,1166,1167,1169],{},"Search your repositories — your own, ones you collaborate on, and your organizations' — across every provider you've connected, and select one. Typing filters by repository name, up to 100 shown, and the footnote under the list says how they're ordered (closest name matches first on GitHub, most recently updated first on Bitbucket); ",[52,1164,1165],{},"Refresh"," beside the search box re-reads the list if a repository you just created isn't there yet, and anything still missing can be added from its URL instead. Plexus always tells you what it actually searched: if the provider is slow or rate-limiting you, it shows what it could read and warns that the list may be missing repositories — ",[52,1168,1165],{}," retries it. On a very large account it searches your most recently updated repositories and says how many it got through, so a repository older than that window is added from its URL rather than found here.",[334,1171,1172,1173,1176,1177,1180],{},"Choose a ",[52,1174,1175],{},"parent folder"," on disk. Plexus clones into a ",[22,1178,1179],{},"\u003Crepo-name>"," subfolder of it; the folder name defaults to the repository name and is editable.",[334,1182,1183,1184,1187],{},"A live progress bar shows the clone's percentage and current phase, with a ",[52,1185,1186],{},"Cancel"," button if you change your mind. When it finishes, the cloned repository is registered as a project just like a local folder.",[10,1189,1190],{},"Private repositories authenticate automatically using the connection Plexus already holds — the token stays on your device, and the clone talks to GitHub or Bitbucket directly.",[105,1192,1194],{"id":1193},"from-a-url","From a URL",[10,1196,1197,1198,853,1201,1204],{},"Paste any ",[22,1199,1200],{},"https",[22,1202,1203],{},"ssh"," git URL to clone it.",[1114,1206,1207,1210,1215],{},[334,1208,1209],{},"Paste the repository URL.",[334,1211,1172,1212,1214],{},[52,1213,1175],{},", adjusting the destination folder name if you like (it defaults to the repository name).",[334,1216,1217,1218,1220],{},"Watch the same live progress bar with ",[52,1219,1186],{},", then Plexus registers the clone as a project.",[10,1222,1223,1225,1226,1229],{},[22,1224,1203],{}," URLs and public repositories use your own local git setup — the keys and credentials ",[22,1227,1228],{},"git clone"," would use.",[47,1231,1232],{},[10,1233,1234,1235,1237],{},"Plexus remembers the last ",[52,1236,1175],{}," you cloned into and offers it as the default next time.",[10,1239,1240],{},"However you add it, the project appears in the tree under the workspace.",[14,1242,1244],{"id":1243},"create-a-session","Create a session",[10,1246,1247,1248,1250],{},"A session is a named Claude Code conversation. On the project row, open the ",[52,1249,1083],{}," menu and pick one of:",[331,1252,1253,1280],{},[334,1254,1255,1258,1259,1262,1263,1266,1267,132,1271,1273],{},[52,1256,1257],{},"New session…"," — name the session, then leave the mode on ",[52,1260,1261],{},"New branch"," and choose a base branch (a smart default is pre-selected). Plexus cuts a fresh worktree and feature branch from that base, keeping the work isolated from your main checkout. Switch the mode to ",[52,1264,1265],{},"Existing branch"," instead when the branch already exists — see ",[99,1268,1270],{"href":1269},"\u002Fdocs\u002Fsessions#existing-branch","Sessions & worktrees",[1124,1272],{},[1096,1274],{"alt":1275,"height":1276,"src":1277,"title":1278,"width":1279},"The New session dialog with a Name field and a Base branch dropdown",305,"\u002Fdocs\u002Fgetting-started\u002Fnew-session-dialog.png","Name the session and pick a base branch, then Create.",407,[334,1281,1282,1285],{},[52,1283,1284],{},"Start session on root tree"," — name the session only, with no base-branch picker. It runs directly in the project's root working tree and starts immediately. Good for quick edits.",[47,1287,1288],{},[10,1289,1290,1291,132],{},"Each standard session is a fully isolated git worktree, on a branch of its own — one Plexus cuts for it, or one that already exists. Run a refactor, a bug fix, and a review of a colleague's branch side by side; none of them can touch each other's files. More in ",[99,1292,1270],{"href":1293},"\u002Fdocs\u002Fsessions",[14,1295,1297],{"id":1296},"start-the-agent","Start the agent",[10,1299,1300,1301,1304,1305,1308],{},"By default, both root-tree and standard sessions launch the moment you create them — a short \"Starting…\" spinner walks through the stages (creating the worktree, running any setup hooks, then starting the agent) before Claude Code appears in the ",[52,1302,1303],{},"Agent"," tab. Prefer to start standard sessions yourself? Click ",[52,1306,1307],{},"Start"," in the Agent tab.",[47,1310,1311],{},[10,1312,1313,1314,1317,1318,1321,1322,1324],{},"That auto-start is ",[52,1315,1316],{},"Start new sessions automatically"," (Settings → Agent) — ",[52,1319,1320],{},"on by default",". Turn it off in ",[99,1323,102],{"href":101}," to create standard sessions stopped and start them by hand.",[14,1326,1328],{"id":1327},"send-your-first-prompt","Send your first prompt",[10,1330,1331],{},"In the Agent tab, type a prompt and press Enter. Watch the activity dot on the session row:",[331,1333,1334,1340,1346],{},[334,1335,1336,1339],{},[52,1337,1338],{},"green",", pulsing — the agent is working,",[334,1341,1342,1345],{},[52,1343,1344],{},"amber"," — it's waiting for your input or approval,",[334,1347,1348,1351],{},[52,1349,1350],{},"gray"," — idle.",[10,1353,1354,1355,1359,1360,1363],{},"These same indicators surface on the ",[99,1356,1358],{"href":1357},"\u002Fdocs\u002Fdashboard","Dashboard",", so you can track several sessions at once. See ",[99,1361,1362],{"href":348},"Session status"," for what each state means.",[1365,1366],"key-table",{":rows":1367},"[[\"Enter\",\"Submit your prompt to the agent\"],[\"⇧Enter\",\"Insert a newline without submitting\"],[\"⌃C\",\"Interrupt the agent mid-turn\"]]",[14,1369,1371],{"id":1370},"explore-the-tabs","Explore the tabs",[10,1373,1374],{},"While the agent works, switch between the per-session tabs:",[190,1376,1377,1387],{},[193,1378,1379],{},[196,1380,1381,1384],{},[199,1382,1383],{},"Tab",[199,1385,1386],{},"What it shows",[209,1388,1389,1398,1407,1416],{},[196,1390,1391,1395],{},[214,1392,1393],{},[52,1394,1303],{},[214,1396,1397],{},"The live Claude Code terminal.",[196,1399,1400,1404],{},[214,1401,1402],{},[52,1403,359],{},[214,1405,1406],{},"A focused diff of the changes the agent has made.",[196,1408,1409,1413],{},[214,1410,1411],{},[52,1412,379],{},[214,1414,1415],{},"The session's working tree as a file browser.",[196,1417,1418,1422],{},[214,1419,1420],{},[52,1421,136],{},[214,1423,1424],{},"Branch status, commits, and staging.",[10,1426,1427,1428,1432,1433,1432,1436,1439,1440,132],{},"Read more about each: the ",[99,1429,1431],{"href":1430},"\u002Fdocs\u002Fagent","Agent tab",", ",[99,1434,1435],{"href":358},"Review tab",[99,1437,1438],{"href":378},"Explorer tab",", and ",[99,1441,369],{"href":368},[14,1443,1445],{"id":1444},"next-steps","Next steps",[331,1447,1448,1453,1464,1471],{},[334,1449,1450,1451,132],{},"Understand the model in ",[99,1452,324],{"href":323},[334,1454,1455,1456,1459,1460,132],{},"Get gitignored files like ",[22,1457,1458],{},".env"," into worktrees with ",[99,1461,1463],{"href":1462},"\u002Fdocs\u002Fworktrees","Worktrees",[334,1465,1466,1467,132],{},"Wrap up by opening a ",[99,1468,1470],{"href":1469},"\u002Fdocs\u002Fpull-requests","pull request",[334,1472,1473,1474,1478],{},"Learn every shortcut on the ",[99,1475,1477],{"href":1476},"\u002Fdocs\u002Fshortcuts","Shortcuts"," page.",{"title":33,"searchDepth":266,"depth":266,"links":1480},[1481,1482,1487,1488,1489,1490,1491],{"id":1060,"depth":266,"text":1061},{"id":1073,"depth":266,"text":1074,"children":1483},[1484,1485,1486],{"id":1108,"depth":271,"text":1109},{"id":1150,"depth":271,"text":1151},{"id":1193,"depth":271,"text":1194},{"id":1243,"depth":266,"text":1244},{"id":1296,"depth":266,"text":1297},{"id":1327,"depth":266,"text":1328},{"id":1370,"depth":266,"text":1371},{"id":1444,"depth":266,"text":1445},"Add a repository and run your first agent session.","Rocket",{},4,{"title":425,"description":1492},"docs\u002Fgetting-started","UeFX06UQrnEkqRHhMkUWyiBYdVi6_l2cYQg438mBYH0",{"id":1500,"title":1501,"body":1502,"description":1795,"extension":277,"group":278,"icon":1796,"meta":1797,"navTitle":324,"navigation":281,"order":1798,"path":323,"seo":1799,"stem":1800,"__hash__":1801},"docs\u002Fdocs\u002Fconcepts.md","Core concepts",{"type":7,"value":1503,"toc":1783},[1504,1507,1511,1514,1568,1571,1581,1595,1600,1603,1617,1639,1642,1661,1670,1674,1685,1689,1692,1712,1718,1722,1725,1745,1754,1758,1765],[10,1505,1506],{},"Plexus nests your work in a three-tier hierarchy and gives every session two independent status indicators — learn both and you can navigate the whole app.",[14,1508,1510],{"id":1509},"the-hierarchy","The hierarchy",[10,1512,1513],{},"Everything lives in the same order, outermost to innermost, and you see it in the left sidebar tree: expand a workspace to reveal its projects, expand a project to reveal its sessions.",[190,1515,1516,1529],{},[193,1517,1518],{},[196,1519,1520,1523,1526],{},[199,1521,1522],{},"Tier",[199,1524,1525],{},"What it is",[199,1527,1528],{},"Holds",[209,1530,1531,1544,1555],{},[196,1532,1533,1538,1541],{},[214,1534,1535],{},[52,1536,1537],{},"Workspace",[214,1539,1540],{},"A named group of related projects",[214,1542,1543],{},"Projects",[196,1545,1546,1550,1553],{},[214,1547,1548],{},[52,1549,304],{},[214,1551,1552],{},"Exactly one git repository",[214,1554,312],{},[196,1556,1557,1562,1565],{},[214,1558,1559],{},[52,1560,1561],{},"Session",[214,1563,1564],{},"One git worktree wrapping one named Claude Code session",[214,1566,1567],{},"The agent, the working tree, the branch",[105,1569,1537],{"id":1570},"workspace",[10,1572,1573,1574,1577,1578,1580],{},"A workspace is a named bucket for grouping projects — one per client, team, or area of your work. There is always exactly one ",[52,1575,1576],{},"default"," workspace, marked with a star and auto-selected on launch. On first run Plexus creates a ",[22,1579,1067],{}," workspace, so the tree is never empty.",[10,1582,1583,1584,1055,1587,1590,1591,1594],{},"Grouping related projects is also where shared configuration pays off: both ",[99,1585,1586],{"href":101},"settings",[99,1588,1589],{"href":388},"hooks"," cascade ",[52,1592,1593],{},"Global → Workspace → Project",", so a workspace is the natural place to set defaults once for similar repos — a common Create hook that installs dependencies, the files copied into each new worktree, auto-start behavior — and let every project inside inherit them, overriding only where one repo differs.",[47,1596,1597],{},[10,1598,1599],{},"You can't delete the last workspace or the current default — set a different workspace as default first.",[105,1601,304],{"id":1602},"project",[10,1604,1605,1606,1608,1609,1612,1613,1616],{},"A project is exactly one git repository registered with Plexus. Adding a project points Plexus at a folder on disk; if it isn't a git repo yet, Plexus offers to run ",[22,1607,1121],{}," for you. Clicking a project's row in the sidebar opens the ",[52,1610,1611],{},"project view"," — a Dashboard tab listing the project's sessions and a Git tab with a full ",[99,1614,1615],{"href":373},"git client"," on the repository's main checkout. Removing a project tears down its sessions but leaves the repository on disk untouched.",[10,1618,1619,1620,1623,1624,1626,1627,1630,1631,1634,1635,1638],{},"You can also ",[52,1621,1622],{},"archive"," a whole project from its ",[22,1625,1083],{}," menu — the project and all of its sessions disappear from the tree but stay restorable, the same way archiving works for a single session. When you archive, Plexus stops every session's agent and asks one question: keep each session's worktree on disk (so a restore is instant and sessions stay resumable), or ",[52,1628,1629],{},"tear down worktrees"," to reclaim disk — running each session's teardown hooks and removing its worktree, optionally with its branch. Either way the project's settings and hooks are preserved. Archived projects live in the ",[52,1632,1633],{},"Archived"," drawer (the button at the bottom of the sidebar), where you can ",[52,1636,1637],{},"Restore"," one or delete it permanently. Your git repository on disk is never touched.",[105,1640,1561],{"id":1641},"session",[10,1643,1644,1645,1648,1649,1652,1653,1656,1657,1660],{},"A session is the unit of work — think ",[52,1646,1647],{},"one session = one feature",". When you start one, Plexus cuts a dedicated git ",[52,1650,1651],{},"worktree"," for it and launches a named Claude Code conversation inside. By default that worktree gets its own new ",[22,1654,1655],{},"plexus\u002F\u003Cname>"," branch off a base branch you choose; you can instead point the session at a ",[52,1658,1659],{},"branch that already exists"," — local or remote-only — to carry on someone's pushed work or to review it. Because each session has its own worktree, sessions in the same project run in parallel without stepping on each other's files.",[10,1662,1663,1664,1666,1667,1669],{},"Not every task needs a whole worktree, though. When you just want a quick edit or review, choose ",[52,1665,1284],{}," to run a session directly in the project's root working tree — no base-branch picker and no isolation, so it launches immediately. Reach for it for fast, throwaway work, and use a standard session when you want the change isolated. See ",[99,1668,1270],{"href":1293}," for the full lifecycle and base-branch options.",[14,1671,1673],{"id":1672},"the-two-status-indicators","The two status indicators",[10,1675,1676,1677,1680,1681,1684],{},"Every session row in the tree and the ",[99,1678,1679],{"href":1357},"dashboard"," carries two indicators that are ",[52,1682,1683],{},"orthogonal"," — they answer different questions and change independently. A session can be idle with an open (green) PR, or working with no PR yet, in any combination.",[105,1686,1688],{"id":1687},"activity","Activity",[10,1690,1691],{},"A small dot shows what the agent is doing right now:",[331,1693,1694,1700,1706],{},[334,1695,1696,1699],{},[52,1697,1698],{},"Working"," — emerald, pulsing. The agent is actively processing a turn.",[334,1701,1702,1705],{},[52,1703,1704],{},"Waiting"," — amber. The agent needs your input or approval.",[334,1707,1708,1711],{},[52,1709,1710],{},"Idle"," — gray. Nothing in flight.",[10,1713,1714,1715,1717],{},"Plexus tracks this automatically through activity hooks installed into each session. See ",[99,1716,1362],{"href":348}," for details, including how to reset a stuck dot.",[105,1719,1721],{"id":1720},"branch-pr-state","Branch \u002F PR state",[10,1723,1724],{},"A branch icon shows where the work stands in the pull-request lifecycle:",[331,1726,1727,1733,1739],{},[334,1728,1729,1732],{},[52,1730,1731],{},"Gray"," — no pull request yet.",[334,1734,1735,1738],{},[52,1736,1737],{},"Green"," — an open pull request exists.",[334,1740,1741,1744],{},[52,1742,1743],{},"Purple"," — the pull request has been merged.",[10,1746,1747,1748,1751,1752,132],{},"In the dashboard, click the PR icon to open the pull request in your browser. Plexus supports ",[52,1749,1750],{},"GitHub and Bitbucket"," — see ",[99,1753,173],{"href":172},[14,1755,1757],{"id":1756},"warm-sessions","Warm sessions",[10,1759,1760,1761,1764],{},"Switching between sessions is instant because Plexus keeps recently-used sessions ",[52,1762,1763],{},"warm"," — their terminal and agent process stay live in the background even while you're looking at another session. A capped number stay warm at once (default 8); exceed the cap and the least-recently-used session is quietly cooled. A cooled session isn't gone — its worktree and conversation are preserved, and switching back resumes it automatically.",[10,1766,1767,1768,1771,1772,1775,1776,320,1778,1782],{},"That cap is the ",[52,1769,1770],{},"Maximum sessions kept ready"," setting (Settings → Advanced), so you can tune it to your hardware: raise it on a powerful machine to keep more sessions instant, or lower it on a modest one to save memory — each warm session keeps a live agent and terminal process resident. Set it to ",[22,1773,1774],{},"0"," for no limit. Adjust it in ",[99,1777,102],{"href":101},[99,1779,1781],{"href":1780},"\u002Fdocs\u002Farchitecture","Architecture"," for how warm sessions work under the hood.",{"title":33,"searchDepth":266,"depth":266,"links":1784},[1785,1790,1794],{"id":1509,"depth":266,"text":1510,"children":1786},[1787,1788,1789],{"id":1570,"depth":271,"text":1537},{"id":1602,"depth":271,"text":304},{"id":1641,"depth":271,"text":1561},{"id":1672,"depth":266,"text":1673,"children":1791},[1792,1793],{"id":1687,"depth":271,"text":1688},{"id":1720,"depth":271,"text":1721},{"id":1756,"depth":266,"text":1757},"Workspaces, projects, sessions, worktrees, and the status indicators.","Boxes",{},5,{"title":1501,"description":1795},"docs\u002Fconcepts","ewd3MSxc_iKk-xJzBroVX8RPiVSi3pBApNtYre13Zbs",{"id":1803,"title":1781,"body":1804,"description":2039,"extension":277,"group":278,"icon":2040,"meta":2041,"navTitle":1781,"navigation":281,"order":2042,"path":1780,"seo":2043,"stem":2044,"__hash__":2045},"docs\u002Fdocs\u002Farchitecture.md",{"type":7,"value":1805,"toc":2032},[1806,1809,1813,1824,1827,1831,1848,1857,1861,1870,1874,1877,1972,1990,2001,2005,2029],[10,1807,1808],{},"Plexus is a native desktop app that wraps the real Claude Code CLI, with a Vue frontend and a Rust backend that does the heavy lifting.",[14,1810,1812],{"id":1811},"native-not-a-browser-tab","Native, not a browser tab",[10,1814,1815,1816,1821,1822,132],{},"Plexus ships as a ",[99,1817,1820],{"href":1818,"rel":1819},"https:\u002F\u002Ftauri.app",[131],"Tauri"," desktop app: a lightweight Vue UI driving a Rust backend. The backend owns everything slow or system-level — PTY terminals, git operations, file IO, and provider calls — so the interface stays responsive while agents and shells run underneath it. You install a signed build, not a web app; see ",[99,1823,264],{"href":263},[10,1825,1826],{},"Choosing Tauri over Electron was deliberate. An Electron app bundles its own copy of Chromium and runs the app's logic in JavaScript on a single main thread — so its memory footprint is heavy from the start and tends to creep up as features pile on, and the more you ask of it at once (many live sessions, terminals, and git operations in parallel) the more that one thread becomes the bottleneck. It's felt most on modest or older hardware. Plexus instead pairs a lightweight system-webview UI with a multithreaded Rust backend, keeping the heavy, concurrent work off the UI thread so the app stays fast as your session count climbs.",[14,1828,1830],{"id":1829},"local-first-by-design","Local-first by design",[10,1832,1833,1834,1836,1837,1839,1840,1843,1844,132],{},"Plexus never sends your code, sessions, or credentials anywhere — there is no account, no sync, and no server-side copy. Plexus drives the ",[22,1835,24],{}," CLI that you already have on your ",[22,1838,44],{},", so it runs on ",[52,1841,1842],{},"your"," Claude subscription rather than calling a hosted API behind your back. The only way any of it reaches us is if you attach a screenshot or a diagnostic log to a report yourself — see ",[99,1845,1847],{"href":1846},"\u002Fdocs\u002Ffeedback","Feedback",[47,1849,1850],{},[10,1851,1852,1853,132],{},"Settings, session state, and history live in a local database on your machine — there is no Plexus account and no server-side config. Secrets are stored in your OS keychain. See ",[99,1854,1856],{"href":1855},"\u002Fdocs\u002Fsecrets","Secrets",[14,1858,1860],{"id":1859},"only-the-active-session-is-mounted","Only the active session is mounted",[10,1862,1863,1864,1866,1867,1869],{},"Plexus can run many sessions in parallel, but it only mounts the UI for the one you're looking at. Idle sessions stay ",[52,1865,1763],{}," in the background — their agent and worktree are alive and processing — so switching between them is instant and nothing loses its place. See ",[99,1868,324],{"href":323}," for how sessions, worktrees, and projects fit together.",[14,1871,1873],{"id":1872},"the-window-at-a-glance","The window at a glance",[10,1875,1876],{},"The app is one window with a few fixed regions:",[190,1878,1879,1889],{},[193,1880,1881],{},[196,1882,1883,1886],{},[199,1884,1885],{},"Region",[199,1887,1888],{},"What lives there",[209,1890,1891,1913,1923,1936,1957],{},[196,1892,1893,1898],{},[214,1894,1895],{},[52,1896,1897],{},"App bar",[214,1899,1900,1901,1904,1905,1907,1908,1912],{},"The Plexus mark, the workspace switcher, the Dashboard \u002F Sessions views, one ",[52,1902,1903],{},"+"," for a new session, the density control, the ",[99,1906,102],{"href":101}," button and a light ⇄ dark theme toggle (all three theme modes live in ",[99,1909,1911],{"href":1910},"\u002Fdocs\u002Fsettings#appearance","Settings → Appearance",")",[196,1914,1915,1920],{},[214,1916,1917],{},[52,1918,1919],{},"Context bar",[214,1921,1922],{},"A full-width band under the app bar naming where you are — project, then session, then the agent's state — and carrying the tools that act on it",[196,1924,1925,1930],{},[214,1926,1927],{},[52,1928,1929],{},"Left tree",[214,1931,1932,1933,1935],{},"Projects and their sessions, plus the ",[99,1934,1358],{"href":1357}," and archived items",[196,1937,1938,1943],{},[214,1939,1940],{},[52,1941,1942],{},"Center",[214,1944,1945,1946,1948,1949,1432,1951,1432,1953,1432,1955],{},"The active ",[99,1947,1641],{"href":1293}," — a tabbed view: ",[99,1950,1303],{"href":1430},[99,1952,359],{"href":358},[99,1954,379],{"href":378},[99,1956,136],{"href":368},[196,1958,1959,1964],{},[214,1960,1961],{},[52,1962,1963],{},"Bottom",[214,1965,1966,1967,1971],{},"A collapsible ",[99,1968,1970],{"href":1969},"\u002Fdocs\u002Fterminal","terminal"," panel rooted in the session's worktree",[10,1973,1974,1975,1978,1979,1982,1983,1986,1987,132],{},"Switch tabs with ",[22,1976,1977],{},"⌘1","–",[22,1980,1981],{},"⌘4",", toggle the terminal with ",[22,1984,1985],{},"⌘J",", and toggle the dashboard with ",[22,1988,1989],{},"⌘0",[47,1991,1992],{},[10,1993,1994,1997,1998,132],{},[22,1995,1996],{},"⌘","\u002FMod is Cmd on macOS and Ctrl on Windows\u002FLinux. The full set lives in ",[99,1999,2000],{"href":1476},"Keyboard shortcuts",[14,2002,2004],{"id":2003},"what-the-backend-handles","What the backend handles",[331,2006,2007,2013,2020],{},[334,2008,2009,2012],{},[52,2010,2011],{},"Terminals"," — each session and scratch shell runs in a real PTY, so interactive tools and TUIs work exactly as they would in your own terminal.",[334,2014,2015,2017,2018,132],{},[52,2016,136],{}," — worktrees, branches, diffs, rebase, merge, and squash are native git operations, not reimplementations. See ",[99,2019,1463],{"href":1462},[334,2021,2022,2025,2026,2028],{},[52,2023,2024],{},"Providers"," — Plexus launches and supervises the ",[22,2027,24],{}," process for each session and streams its output to the UI.",[10,2030,2031],{},"The result is a thin client over fast native plumbing: the UI is just a view, and the work happens close to your filesystem.",{"title":33,"searchDepth":266,"depth":266,"links":2033},[2034,2035,2036,2037,2038],{"id":1811,"depth":266,"text":1812},{"id":1829,"depth":266,"text":1830},{"id":1859,"depth":266,"text":1860},{"id":1872,"depth":266,"text":1873},{"id":2003,"depth":266,"text":2004},"How Plexus is built — a thin, local-first Tauri desktop app.","Package",{},6,{"title":1781,"description":2039},"docs\u002Farchitecture","xSTjuqty0y48QLFJFf92csvtt37IyESuFfwNgWIsuJc",{"id":2047,"title":1358,"body":2048,"description":2371,"extension":277,"group":2372,"icon":2373,"meta":2374,"navTitle":1358,"navigation":281,"order":2375,"path":1357,"seo":2376,"stem":2377,"__hash__":2378},"docs\u002Fdocs\u002Fdashboard.md",{"type":7,"value":2049,"toc":2361},[2050,2053,2061,2065,2080,2083,2134,2141,2145,2168,2184,2193,2197,2208,2214,2259,2262,2266,2269,2278,2282,2298,2302,2309,2313,2340,2344],[10,2051,2052],{},"The Global Dashboard is one live table of every session across all your workspaces and projects — current activity and pull-request state, at a glance.",[10,2054,2055,2056,2060],{},"It shows your active work only: archived sessions, and the sessions of an ",[99,2057,2059],{"href":2058},"\u002Fdocs\u002Fconcepts#project","archived project",", drop out of the table (and the header counts) until you restore them.",[14,2062,2064],{"id":2063},"open-the-dashboard","Open the dashboard",[10,2066,2067,2068,2070,2071,2073,2074,2076,2077,2079],{},"Press ",[22,2069,1989],{},", or click the ",[52,2072,1358],{}," button in the left sidebar. (",[22,2075,1996],{}," is Cmd on macOS, Ctrl on Windows and Linux.) Press ",[22,2078,1989],{}," or click the button again to toggle it off and return to the session view.",[10,2081,2082],{},"The right pane switches to a session table with these columns:",[190,2084,2085,2095],{},[193,2086,2087],{},[196,2088,2089,2092],{},[199,2090,2091],{},"Column",[199,2093,2094],{},"Shows",[209,2096,2097,2105,2112,2119,2127],{},[196,2098,2099,2102],{},[214,2100,2101],{},"State",[214,2103,2104],{},"The activity dot — working, waiting, or idle — ringed in blue when background subagents are running",[196,2106,2107,2109],{},[214,2108,1561],{},[214,2110,2111],{},"The session name",[196,2113,2114,2116],{},[214,2115,304],{},[214,2117,2118],{},"The project the session belongs to",[196,2120,2121,2124],{},[214,2122,2123],{},"Branch",[214,2125,2126],{},"The session's worktree branch",[196,2128,2129,2131],{},[214,2130,1537],{},[214,2132,2133],{},"The workspace the project lives in",[10,2135,2136,2137,2140],{},"Each row carries the same indicators as the navigation tree — a pulsing activity dot and a PR badge. See ",[99,2138,2139],{"href":348},"Status & indicators"," for what every color and icon means.",[14,2142,2144],{"id":2143},"summary-counts","Summary counts",[10,2146,2147,2148,2151,2152,2155,2156,2159,2160,2163,2164,2167],{},"A header above the table totals every session by state: green ",[52,2149,2150],{},"working"," (agents producing output), amber ",[52,2153,2154],{},"waiting"," (sessions that need your input), and gray ",[52,2157,2158],{},"idle"," (started sessions with no active turn), plus green ",[52,2161,2162],{},"open"," and purple ",[52,2165,2166],{},"merged"," pull-request counts. Every session lands in exactly one of the three state counts, so the three always add up to the number of sessions in view.",[10,2169,2170,2171,2174,2175,2179,2180,2183],{},"One more count appears when there is something to report: ",[52,2172,2173],{},"N delegating"," — how many sessions have ",[99,2176,2178],{"href":2177},"\u002Fdocs\u002Fstatus#background-subagents","background subagents"," running. Its glyph is a blue ring rather than a filled dot, matching the row indicator, because it cuts across the other three counts rather than adding to them: a session with delegated work running is still counted as working, waiting, or idle. Hover it for the breakdown — ",[91,2181,2182],{},"\"3 background subagents running across 2 sessions\"",". The chip is hidden when nothing is delegated.",[47,2185,2186],{},[10,2187,2188,2189,2192],{},"The counts always reflect ",[52,2190,2191],{},"all"," sessions across the whole app, even when you filter the table below to a single workspace — so the header tells you what's happening everywhere while you focus the list on one area.",[14,2194,2196],{"id":2195},"filter-and-sort","Filter and sort",[10,2198,2199,2200,2203,2204,2207],{},"The ",[52,2201,2202],{},"Filter by workspace"," dropdown defaults to ",[52,2205,2206],{},"All workspaces","; pick a workspace name to narrow the table to its sessions. Only the table is filtered — the summary counts stay global.",[10,2209,2199,2210,2213],{},[52,2211,2212],{},"Sort sessions"," dropdown reorders the table:",[190,2215,2216,2226],{},[193,2217,2218],{},[196,2219,2220,2223],{},[199,2221,2222],{},"Mode",[199,2224,2225],{},"Order",[209,2227,2228,2236,2244,2251],{},[196,2229,2230,2233],{},[214,2231,2232],{},"Needs input first",[214,2234,2235],{},"Waiting, then working, then idle (the default). Within each group, sessions with background subagents running come first",[196,2237,2238,2241],{},[214,2239,2240],{},"Recently active",[214,2242,2243],{},"Most recent activity first",[196,2245,2246,2248],{},[214,2247,1537],{},[214,2249,2250],{},"By workspace, then project, then session",[196,2252,2253,2256],{},[214,2254,2255],{},"Name",[214,2257,2258],{},"Alphabetical by session name",[10,2260,2261],{},"Your sort choice is remembered while the app is open and resets to the default the next time you launch Plexus.",[14,2263,2265],{"id":2264},"jump-to-a-session","Jump to a session",[10,2267,2268],{},"Click anywhere on a row to focus that session: Plexus switches to the session view, selects the session, and expands its project and workspace in the sidebar tree. The one exception is the PR badge — clicking it opens the pull request in your browser instead.",[10,2270,2271,2272,2275,2276,132],{},"If you already know which session you want, ",[22,2273,2274],{},"⌘K"," gets there without the dashboard: it searches every session and project by name, branch, project or workspace. See ",[99,2277,2000],{"href":1476},[14,2279,2281],{"id":2280},"the-project-dashboard","The project dashboard",[10,2283,2284,2285,2287,2288,2290,2291,2293,2294,2297],{},"The same table exists scoped to a single project: click a project's row in the sidebar tree to open the ",[99,2286,1611],{"href":373},", whose ",[52,2289,1358],{}," tab lists only that project's sessions — the same columns and live indicators, summary counts for just this project, and the same sort modes (minus ",[91,2292,1537],{},", which is meaningless within one project). A ",[52,2295,2296],{},"New session"," button sits in the header, so starting the next piece of work never leaves the view. As everywhere else, archived sessions are excluded.",[14,2299,2301],{"id":2300},"empty-state","Empty state",[10,2303,2304,2305,2308],{},"Before you've created any sessions, the dashboard shows a centered ",[52,2306,2307],{},"No sessions yet"," message explaining that sessions from across your workspaces and projects appear here with live activity and PR state. Your first session shows up automatically once you create it.",[14,2310,2312],{"id":2311},"adding-repositories","Adding repositories",[10,2314,2315,2316,1084,2318,2320,2321,2323,2324,2327,2328,2331,2332,2335,2336,2339],{},"Projects come from the navigation tree, not the dashboard table: hover a workspace, open its ",[52,2317,1083],{},[52,2319,1087],{}," (empty workspaces show an inline ",[52,2322,1091],{},"). You can add a project from a ",[52,2325,2326],{},"local folder",", by ",[52,2329,2330],{},"searching a connected GitHub or Bitbucket account"," and cloning a repository, or by ",[52,2333,2334],{},"cloning a git URL"," — the two clone flows show a live progress bar and register the result as a project. See ",[99,2337,1074],{"href":2338},"\u002Fdocs\u002Fgetting-started#add-a-repository"," for the full walkthrough.",[14,2341,2343],{"id":2342},"related","Related",[331,2345,2346,2351,2356],{},[334,2347,2348,2350],{},[99,2349,425],{"href":424}," — add your first repository and run a session",[334,2352,2353,2355],{},[99,2354,2139],{"href":348}," — what the activity dots and PR badges mean",[334,2357,2358,2360],{},[99,2359,2000],{"href":1476}," — the full shortcut reference",{"title":33,"searchDepth":266,"depth":266,"links":2362},[2363,2364,2365,2366,2367,2368,2369,2370],{"id":2063,"depth":266,"text":2064},{"id":2143,"depth":266,"text":2144},{"id":2195,"depth":266,"text":2196},{"id":2264,"depth":266,"text":2265},{"id":2280,"depth":266,"text":2281},{"id":2300,"depth":266,"text":2301},{"id":2311,"depth":266,"text":2312},{"id":2342,"depth":266,"text":2343},"The bird's-eye view — every session across all workspaces.","Working with projects","LayoutGrid",{},10,{"title":1358,"description":2371},"docs\u002Fdashboard","Cii6eAHALyaxR_D1Ju9t0o9mxB04jIjCTUdSYVaz59Y",{"id":2380,"title":2381,"body":2382,"description":4045,"extension":277,"group":2372,"icon":4046,"meta":4047,"navTitle":4048,"navigation":281,"order":4049,"path":373,"seo":4050,"stem":4051,"__hash__":4052},"docs\u002Fdocs\u002Fproject-git.md","Project Git client",{"type":7,"value":2383,"toc":4018},[2384,2391,2400,2404,2415,2425,2428,2435,2439,2452,2456,2479,2487,2491,2505,2557,2564,2657,2664,2679,2683,2692,2706,2709,2728,2752,2766,2770,2818,2879,2915,2919,2936,2942,2975,2985,2999,3013,3025,3035,3057,3061,3153,3168,3200,3209,3213,3220,3223,3239,3259,3282,3299,3303,3316,3325,3329,3348,3358,3362,3365,3398,3408,3425,3433,3462,3479,3494,3498,3504,3519,3522,3542,3560,3585,3616,3638,3649,3669,3680,3685,3704,3714,3727,3732,3770,3773,3780,3808,3811,3815,3824,3833,3837,3840,3847,3850,3904,3927,3935,3939,3950,3960,3964,3975,3977],[10,2385,2386,2387,2390],{},"The project view puts a full git client on your repository's ",[52,2388,2389],{},"main checkout"," — a commit graph with branches, tags, and stashes, plus pull, push, staging, context-menu branch surgery, and in-app conflict resolution.",[10,2392,2393,2394,2396,2397,2399],{},"This is the project-level counterpart to the session's ",[99,2395,369],{"href":368},": that one manages a single session's worktree branch, while this one manages the repository itself. Throughout this page ",[22,2398,1996],{}," is Cmd on macOS and Ctrl on Windows and Linux.",[14,2401,2403],{"id":2402},"open-the-project-view","Open the project view",[10,2405,2406,2407,2410,2411,2414],{},"Click a ",[52,2408,2409],{},"project row"," in the left sidebar. This opens the project view and expands the project's sessions — it never collapses them. To collapse or expand a project without opening it, click the small ",[52,2412,2413],{},"chevron"," on the row instead; the two are separate targets, so the chevron never opens the view.",[10,2416,2417,2418,2420,2421,2424],{},"The header shows the project's name and repository path, a ",[52,2419,2296],{}," button, and an ",[52,2422,2423],{},"×"," to close the view. Below it sit three tabs:",[1365,2426],{":rows":2427},"[[\"⌘1\",\"Switch to the Dashboard tab\"],[\"⌘2\",\"Switch to the Git tab\"],[\"⌘3\",\"Switch to the Terminal tab\"]]",[10,2429,2430,2431,2434],{},"These share their default combos with the session tab shortcuts — a session and a project are never in view at the same time, so they don't conflict, and each is ",[99,2432,2433],{"href":1476},"rebindable"," on its own. Plexus remembers which tab you left open per project.",[14,2436,2438],{"id":2437},"the-dashboard-tab","The Dashboard tab",[10,2440,2441,2442,2445,2446,2448,2449,132],{},"The Dashboard tab is the ",[99,2443,2444],{"href":1357},"global dashboard's"," session table scoped to this one project: every unarchived session with its live activity dot, branch, and PR badge, per-project summary counts in the header, the same sort modes, and a ",[52,2447,2296],{}," button. Click a row to jump to that session. See ",[99,2450,1358],{"href":2451},"\u002Fdocs\u002Fdashboard#the-project-dashboard",[14,2453,2455],{"id":2454},"the-git-tab","The Git tab",[10,2457,2458,2459,2462,2463,2466,2467,2470,2471,2474,2475,132],{},"The Git tab is laid out in three resizable panes: the ",[52,2460,2461],{},"refs panel"," on the left (branches, remotes, worktrees, stashes, tags), the ",[52,2464,2465],{},"commit graph"," in the center, and a ",[52,2468,2469],{},"detail pane"," on the right showing whichever commit — or your uncommitted work — is selected. A toolbar with the branch switcher and sync actions runs across the top. Diffs never squeeze into the detail pane: clicking a file there opens its diff ",[52,2472,2473],{},"full-width"," in place of the refs panel and graph — see ",[99,2476,2478],{"href":2477},"#the-detail-pane","The detail pane",[10,2480,2481,2482,2486],{},"Everything operates on the project's primary checkout — the folder you registered as the project — never on a session's worktree. Plexus keeps the tab current on its own: after its own operations, whenever you return to the window, and — while the tab is open — by checking every few seconds for git activity from your sessions or an outside terminal. New commits from your remotes arrive on their own too, through ",[99,2483,2485],{"href":2484},"#automatic-fetching","automatic fetching",". The toolbar's refresh button forces a fetch and reload any time.",[14,2488,2490],{"id":2489},"the-commit-graph","The commit graph",[10,2492,2493,2494,1432,2497,2500,2501,2504],{},"The center pane draws the repository's full history as a lane graph, GitKraken-style: colored lanes trace each branch line — running unbroken through the merges that join them — and each commit renders as a dot with the author's avatar inside, ringed in the lane's color. Merge commits stay small hollow dots. The commit's subject fills the row, with a compact relative age (",[22,2495,2496],{},"2h",[22,2498,2499],{},"3d",") on the right edge. The graph is virtualized and extends itself as you scroll — deep histories load in pages automatically, with no ",[91,2502,2503],{},"Load more"," button to press.",[10,2506,2507,2508,2511,2512,2515,2516,2519,2520,2523,2524,2527,2528,2532,2533,2536,2537,2540,2541,2544,2545,2548,2549,2552,2553,2556],{},"Branch and tag ",[52,2509,2510],{},"labels"," sit in a fixed column on the graph's left edge, each tied to its commit's dot by a thin connector line in the branch's color. A branch gets ",[52,2513,2514],{},"one label"," wherever it lives, with presence icons telling you where: a ",[52,2517,2518],{},"computer"," icon when the branch exists locally, a ",[52,2521,2522],{},"cloud"," icon when it exists on a remote, and both together when local and remote point at the same commit — hover the label for the full remote-qualified names. A branch that exists only on a remote shows the bare branch name with just the cloud icon, so a glance still tells you whether a tip is only on your machine, only on the remote, or both. The checked-out branch's label is highlighted with a check mark, and tags keep their tag icon. ",[52,2525,2526],{},"Right-click a label"," and you get that branch's or tag's own ",[99,2529,2531],{"href":2530},"#context-menus","context menu"," — the same actions as its row in the ",[99,2534,2461],{"href":2535},"#the-refs-panel","; right-clicking anywhere else on the row still gives you the commit menu. A row with several refs shows the first label and folds the rest into a ",[22,2538,2539],{},"+N"," badge — ",[52,2542,2543],{},"hover it, click it, or focus it and press Enter"," for a small panel listing the folded refs, each with the same right-click menu. ",[52,2546,2547],{},"Click a folded branch to check it out","; clicking a folded ",[52,2550,2551],{},"tag"," jumps the graph to its commit instead, because checking a tag out detaches HEAD and that stays a deliberate menu action. ",[52,2554,2555],{},"Double-click a branch label to check the branch out"," — a remote label with no local branch yet creates a local tracking branch first; a remote label whose local branch already exists switches to that local branch and fast-forwards it to the remote (a pull), leaving it untouched if the two have diverged. Either way it matches checking the branch out from the refs panel.",[10,2558,2559,2560,2563],{},"Branch labels can also be ",[52,2561,2562],{},"dragged onto one another",": drop one branch's label on another's and a menu offers the actions that fit that pair. Tags can't be dragged, and a drop with nothing to offer simply does nothing.",[331,2565,2566,2572,2582,2630,2647],{},[334,2567,2568,2571],{},[52,2569,2570],{},"Fast-forward"," the dragged branch to the target — offered when the dragged branch is local; it refuses cleanly if the two have diverged.",[334,2573,2574,2577,2578,2581],{},[52,2575,2576],{},"Push"," the dragged branch to the target's ",[52,2579,2580],{},"remote branch"," — offered when the dragged branch is local and the target exists on a remote; it pushes your commits onto that remote branch even though the names differ. The push is never forced — it refuses if the remote branch has commits the dragged branch doesn't.",[334,2583,2584,2587,2588,2591,2592,2587,2595,2598,2599,2602,2603,2606,2607,2610,2611,2613,2614,2616,2617,2620,2621,2624,2625,2629],{},[52,2585,2586],{},"Merge"," the dragged branch ",[52,2589,2590],{},"into"," the target, or ",[52,2593,2594],{},"rebase",[52,2596,2597],{},"onto"," the target — offered for any two different branches, and always in the direction you dragged (dropping ",[22,2600,2601],{},"develop"," on ",[22,2604,2605],{},"accept"," offers ",[91,2608,2609],{},"Merge develop into accept","). Because git can only merge or rebase the checked-out branch, Plexus first checks out the receiving branch (for a merge) or the moving branch (for a rebase) when it isn't already current — so after ",[91,2612,2609],{}," you end up on ",[22,2615,2605],{},". Both use the same confirm dialogs as the ",[99,2618,2619],{"href":2530},"context menus",": merge offers ",[22,2622,2623],{},"--no-ff",", and conflicts flip the tab into ",[99,2626,2628],{"href":2627},"#conflict-resolution","conflict resolution"," as usual.",[334,2631,2632,2635,2636,2639,2640,2639,2643,2646],{},[52,2633,2634],{},"Reset"," the current branch to the target's tip (",[52,2637,2638],{},"Soft"," \u002F ",[52,2641,2642],{},"Mixed",[52,2644,2645],{},"Hard",") — offered only when you drag the checked-out branch itself; a hard reset keeps its typed confirmation.",[334,2648,2649,2652,2653,2656],{},[52,2650,2651],{},"Start a pull request"," from the dragged branch's remote counterpart to the target's — offered when both branches exist on the same remote. A small dialog asks for a title (required) and an optional description, then Plexus creates the pull request on your provider — GitHub today — using the same authentication as the session-level ",[99,2654,2655],{"href":1469},"Pull requests"," flow, and the success toast links to the new PR. Unlike the session flow, there's no AI-drafted description here.",[10,2658,2659,2660,132],{},"Operations that change the working tree ride the usual ",[99,2661,2663],{"href":2662},"#the-busy-checkout-guard","busy-checkout guard",[10,2665,2199,2666,2669,2670,2674,2675,2678],{},[52,2667,2668],{},"Uncommitted changes"," row is pinned at the top with a live count of changed files — click it to open the ",[99,2671,2673],{"href":2672},"#stage-and-commit","staging pane",". An empty repository shows ",[52,2676,2677],{},"No commits yet","; the row for uncommitted work still works, so you can stage and make the first commit from here.",[105,2680,2682],{"id":2681},"author-avatars","Author avatars",[10,2684,2685,2686,2691],{},"Avatars come from ",[99,2687,2690],{"href":2688,"rel":2689},"https:\u002F\u002Fgravatar.com",[131],"Gravatar",", matched by a one-way SHA-256 hash of each commit author's email — the address itself is never sent, results are cached on disk, and authors without a Gravatar get locally-drawn initials on a stable color.",[47,2693,2694],{},[10,2695,2696,2697,2700,2701,2703,2704,132],{},"Avatar lookups are the only network requests this tab makes beyond your git remotes. Turn them off with the global ",[52,2698,2699],{},"Show commit author avatars from Gravatar"," setting (Settings → Git & PRs) and Plexus renders initials only, with no request at all — see ",[99,2702,102],{"href":101}," and the ",[99,2705,472],{"href":471},[14,2707,2478],{"id":2708},"the-detail-pane",[10,2710,2711,2712,2715,2716,2719,2720,2723,2724,2727],{},"Selecting a commit fills the right pane with a ",[52,2713,2714],{},"header"," — the author's avatar, the sha, the commit's parents, and a changed-file count — above the list of ",[52,2717,2718],{},"changed files",", switchable between a flat ",[52,2721,2722],{},"List"," and a folder ",[52,2725,2726],{},"Tree",". Selecting a commit never opens a diff by itself.",[10,2729,2730,2733,2734,2736,2737,2740,2741,2743,2744,2747,2748,2751],{},[52,2731,2732],{},"Click a file"," and its diff opens ",[52,2735,2473],{},", replacing the refs panel and commit graph; the detail pane stays put on the right, so you can step through the commit's files without losing your place. The diff follows the ",[52,2738,2739],{},"Unified \u002F Split"," toggle above it — one app-wide preference shared with the ",[99,2742,1435],{"href":358},". Close the diff with its ",[52,2745,2746],{},"✕"," or press ",[52,2749,2750],{},"Escape"," to return to the graph.",[10,2753,2754,2755,2757,2758,2761,2762,2765],{},"Selecting ",[52,2756,2668],{}," works the same way: the detail pane holds the ",[99,2759,2760],{"href":2672},"staging lists and commit composer",", and a clicked file's diff — or a conflicted file's ",[99,2763,2764],{"href":2627},"resolve pane"," — takes the full-width spot while you keep staging and committing from the right.",[14,2767,2769],{"id":2768},"the-refs-panel","The refs panel",[10,2771,2772,2773,2776,2777,2780,2781,2784,2785,2789,2790,1432,2792,1439,2795,2798,2799,2802,2803,1055,2806,2809,2810,2813,2814,2817],{},"The left panel lists every ref in collapsible sections, each with a count: ",[52,2774,2775],{},"Local"," branches, one section per ",[52,2778,2779],{},"remote"," (e.g. ",[22,2782,2783],{},"origin"," — those sections are also where remotes are ",[99,2786,2788],{"href":2787},"#remotes","added, edited and removed","), ",[52,2791,1463],{},[52,2793,2794],{},"Stashes",[52,2796,2797],{},"Tags",". Names containing ",[22,2800,2801],{},"\u002F"," nest into folders, so ",[22,2804,2805],{},"feature\u002Flogin",[22,2807,2808],{},"feature\u002Fsearch"," group under ",[22,2811,2812],{},"feature",". The ",[52,2815,2816],{},"Filter refs…"," box at the top narrows every section at once.",[10,2819,2820,2821,2826,2827,2830,2831,2834,2835,2839,2840,2801,2843,2846,2847,2849,2850,2852,2853,2855,2856,2859,2860,2863,2864,2867,2868,2871,2872,2874,2875,132],{},"Clicking a branch or tag jumps the graph to its commit; ",[52,2822,2823,2824],{},"right-clicking opens its ",[99,2825,2531],{"href":2530}," — the same menu the matching label carries in the graph; ",[52,2828,2829],{},"double-clicking a branch checks it out"," (a remote branch with no local copy gets a local tracking branch first; one that already has a local branch switches to it and fast-forwards it to the remote). Branch rows also ",[52,2832,2833],{},"drag onto one another"," for the same ",[99,2836,2838],{"href":2837},"#the-commit-graph","drop menu as the graph"," — handy when the branch you want to merge into, rebase onto, or push is scrolled out of view in the graph. Local branch rows also carry the sync state against their upstream: ",[22,2841,2842],{},"↑",[22,2844,2845],{},"↓"," ahead\u002Fbehind counts, plus a ",[52,2848,2522],{}," icon when the branch is fully on its remote or a ",[52,2851,2518],{}," icon when its latest commits exist only locally. The Worktrees section lists the repository's linked worktrees and their branches — with Plexus, that's typically one per ",[99,2854,1641],{"href":1293},". Each row names the session that owns it, or reads ",[22,2857,2858],{},"project checkout"," for the repository itself. A row owned by an ",[52,2861,2862],{},"archived"," session says so — archiving never removed the worktree, so that folder is what restoring the session would resume into. A worktree whose folder git can no longer find is struck through and badged ",[52,2865,2866],{},"missing","; one that has been locked carries a ",[52,2869,2870],{},"locked"," badge with the reason. Right-clicking any row opens its ",[99,2873,2531],{"href":2530},", which is where you clean both of those up — see ",[99,2876,2878],{"href":2877},"#when-a-branch-is-locked-to-a-worktree","When a branch is locked to a worktree",[10,2880,2881,2882,2885,2886,1432,2889,1439,2892,2895,2896,2899,2900,2903,2904,2907,2908,2911,2912,132],{},"Hovering a ",[52,2883,2884],{},"stash"," row reveals ",[52,2887,2888],{},"Apply",[52,2890,2891],{},"Pop",[52,2893,2894],{},"Drop"," actions. Drop asks for a second click (the button flips to ",[91,2897,2898],{},"Drop?"," for a moment) instead of a dialog. Stash rows also have a ",[52,2901,2902],{},"right-click menu"," with those same two actions plus ",[52,2905,2906],{},"Create branch from stash…"," and a ",[52,2909,2910],{},"Drop…"," that confirms in a dialog naming the stash — see ",[99,2913,2914],{"href":2530},"Context menus",[14,2916,2918],{"id":2917},"remotes","Remotes",[10,2920,2921,2922,2924,2925,2927,2928,2931,2932,2935],{},"Each ",[52,2923,2779],{}," the repository is configured with — ",[22,2926,2783],{},", an ",[22,2929,2930],{},"upstream"," you added, a mirror on a network share — gets its own section in the refs panel, holding the branches Plexus last fetched from it. The section header is the remote itself: ",[52,2933,2934],{},"hover it"," to see the URL it points at, and the separate push URL underneath when it has one.",[10,2937,2938,2941],{},[52,2939,2940],{},"Right-click that header"," to manage it:",[331,2943,2944,2954,2960,2966],{},[334,2945,2946,2949,2950,2953],{},[52,2947,2948],{},"Edit remote…"," — rename it, point it at a different URL, or give it a separate ",[52,2951,2952],{},"push URL"," so fetches and pushes go to different places. Clear the push URL again by emptying the field.",[334,2955,2956,2959],{},[52,2957,2958],{},"Add remote…"," — add another one, by name and URL. An HTTPS or SSH URL, or a path to a local repository, all work.",[334,2961,2962,2965],{},[52,2963,2964],{},"Remove remote…"," — drop it from this repository.",[334,2967,2968,2639,2971,2974],{},[52,2969,2970],{},"Copy URL",[52,2972,2973],{},"Copy remote name"," — for pasting into a terminal or a message.",[10,2976,2977,2980,2981,2984],{},[52,2978,2979],{},"Adding a remote doesn't contact it."," The dialog's ",[52,2982,2983],{},"Fetch after adding"," switch (on by default) runs an ordinary fetch straight afterwards, so its branches show up right away — but the two are separate steps, and a URL typo or a credential problem is reported as a failed fetch against a remote that was still added successfully, rather than as an add that half-worked.",[10,2986,2987,2988,2991,2992,2994,2995,2998],{},"If the repository has ",[52,2989,2990],{},"no remotes at all",", the refs panel says so and offers ",[52,2993,2958],{}," there; the same item sits in the ",[52,2996,2997],{},"Pull"," button's menu, since with nothing to pull from there is no section header to right-click.",[10,3000,3001,3004,3005,3008,3009,3012],{},[52,3002,3003],{},"Renaming"," is the safe rewrite: git moves the remote's branches to the new name (",[22,3006,3007],{},"upstream\u002Fmain"," becomes ",[22,3010,3011],{},"fork\u002Fmain",") and repoints every local branch that was tracking them, so nothing is lost and nothing needs re-setting afterwards.",[47,3014,3015],{},[10,3016,3017,3018,3021,3022,3024],{},"If a remote's URL has a ",[52,3019,3020],{},"password or token embedded in it",", Plexus shows the URL without it — and the Edit dialog leaves that field empty, with the stripped URL as a hint. Leave it empty and the stored URL, credential and all, is kept exactly as it is; type a new one and it replaces the whole thing, so include the credential if you still need it there. The same guard costs one thing: a ",[52,3023,2952],{}," that stores a credential can't be cleared from this dialog, because its field starts empty either way. A remote that git is configured to fetch from — or push to — at several URLs at once can't be edited here at all: Plexus disables the field and says so, because changing one of those at a time isn't something git can do.",[10,3026,3027,3030,3031,3034],{},[52,3028,3029],{},"Removing"," a remote deletes the copies of its branches on your machine and clears the upstream of every local branch that was tracking one. The confirmation spells that out first — it lists the branch copies that go, counts the locals that lose their upstream, and says how many running sessions share the configuration you are about to change. Your own branches and their commits stay exactly where they are, and ",[52,3032,3033],{},"nothing changes on the server"," — the remote repository, and everyone else's copy of it, is untouched.",[47,3036,3037],{"tone":69},[10,3038,3039,3040,3043,3044,3048,3049,3051,3052,3054,3055,132],{},"Remotes belong to the ",[52,3041,3042],{},"repository",", not to a session: every session of this project works in a linked worktree of the same checkout, so adding, renaming or removing one changes it for all of them at once, immediately. Renaming or removing the remote called ",[52,3045,3046],{},[22,3047,2783],{}," costs one more thing — Plexus resolves a project's pull requests through ",[22,3050,2783],{},", so its record of which PR belongs to which session is cleared, along with the PR badges showing it. Nothing is lost on the provider: the links come back on the next PR refresh, worked out from wherever ",[22,3053,2783],{}," now points. See ",[99,3056,2655],{"href":1469},[14,3058,3060],{"id":3059},"the-toolbar","The toolbar",[331,3062,3063,3077,3109,3134,3144],{},[334,3064,3065,3068,3069,3072,3073,3076],{},[52,3066,3067],{},"Branch switcher"," — shows the checked-out branch (or a short commit id with a ",[22,3070,3071],{},"detached"," badge). Open it to filter and check out another local branch, or pick ",[52,3074,3075],{},"Create branch…"," to branch from the current head, optionally checking it out immediately.",[334,3078,3079,3081,3082,3085,3086,3089,3090,1432,3093,1439,3096,2813,3099,3102,3103,3105,3106,3108],{},[52,3080,2997],{}," — a split button. The main click runs your default action; the arrow opens the full menu with the same four actions as the ",[52,3083,3084],{},"Default Pull action"," setting: ",[52,3087,3088],{},"Fetch all (download only)"," (all remotes, pruning deleted branches), ",[52,3091,3092],{},"Fast-forward if possible (ff)",[52,3094,3095],{},"Fast-forward only (ff-only)",[52,3097,3098],{},"Rebase",[52,3100,3101],{},"Default action"," picker in the same menu saves your choice for this project — it's the ",[52,3104,3084],{}," setting (Settings → Git & PRs), which defaults to Fast-forward if possible and can also be set globally in ",[99,3107,102],{"href":101},". Pull disables with an explanatory tooltip when there's nothing it could do — no remotes, a detached HEAD, or a branch with no upstream.",[334,3110,3111,3113,3114,2801,3116,3118,3119,3122,3123,3125,3126,3129,3130,3133],{},[52,3112,2576],{}," — pushes the current branch to its upstream, with ",[22,3115,2842],{},[22,3117,2845],{}," ahead\u002Fbehind counts alongside. If the branch has no upstream yet, a ",[52,3120,3121],{},"Publish branch?"," prompt offers to push it to ",[22,3124,2783],{}," and set the upstream in one go. If the remote has diverged — you amended, rebased, or reset a branch that was already pushed — git rejects the push and Plexus asks first: a ",[52,3127,3128],{},"Force push?"," prompt offers to overwrite the remote with ",[22,3131,3132],{},"--force-with-lease",", pinned to the exact remote state that rejection saw — if anyone else pushes in the meantime, the force push fails instead of overwriting their work. Cancel to leave the remote untouched. If the remote holds work you haven't fetched at all, Plexus doesn't offer the force — fetch first, then decide.",[334,3135,3136,2639,3139,3141,3142,132],{},[52,3137,3138],{},"Stash",[52,3140,2891],{}," — stash all changes including untracked files, or pop the newest stash. Individual stashes are managed from the ",[99,3143,2461],{"href":2535},[334,3145,3146,3148,3149,3152],{},[52,3147,1165],{}," — fetch from your remotes, then reload the graph, refs, and status. Use it when you want to be certain you're looking at the latest, rather than waiting for the next automatic fetch. Because you asked for it, this fetch authenticates exactly like ",[52,3150,3151],{},"Fetch all"," does — it can use your credential helper or ask for an SSH key passphrase, where a background fetch never will. If the fetch couldn't run — another git operation is already using the repository, it has no remotes, or a leftover lock file is blocking it — Plexus says so rather than quietly showing you the same local state again.",[10,3154,3155,3156,3159,3160,3162,3163,3167],{},"Every one of these talks to your remotes with ",[52,3157,3158],{},"your own"," git credentials. If your machine has none for an ",[22,3161,1200],{}," remote, a ",[99,3164,3166],{"href":3165},"\u002Fdocs\u002Fconnections#fetching-pulling-and-pushing","connected provider"," is tried as a fallback — and if that doesn't work either, the error names the host that refused and what to do next, rather than reporting a password prompt you never saw.",[10,3169,3170,3171,3174,3175,2801,3177,3179,3180,3183,3184,3187,3188,3191,3192,3195,3196,3199],{},"Next to Refresh, a small note tells you ",[52,3172,3173],{},"how fresh what you're looking at actually is"," — \"Fetched 3m ago\", or \"Never fetched\" for a repository nothing has fetched into yet. This matters more than it sounds: the ",[22,3176,2842],{},[22,3178,2845],{}," counts are worked out against the copy of the remote on your machine, so \"↓0\" only means \"nothing to pull ",[91,3181,3182],{},"as of the last fetch","\". The note tells you when that was. It spins while a fetch is running and turns amber, with the reason in its tooltip, when something is wrong: ",[52,3185,3186],{},"\"Fetch failed\""," after a few failures in a row — a broken remote URL, an expired token, or simply being offline — or ",[52,3189,3190],{},"\"Fetch blocked\""," when a leftover ",[22,3193,3194],{},".lock"," file in the repository is stopping fetches from running at all (close any other git process using the repository; if none is running, delete the leftover lock file the tooltip describes). Both warnings are about ",[91,3197,3198],{},"automatic"," fetching, so they go away if you turn it off — the note then just keeps telling you how long ago the repository was last fetched, by anything.",[10,3201,3202,3203,3208],{},"When you are behind, the ",[52,3204,3205],{},[22,3206,3207],{},"↓N"," count is clickable: one click runs your default Pull action for those commits.",[105,3210,3212],{"id":3211},"automatic-fetching","Automatic fetching",[10,3214,3215,3216,3219],{},"Plexus fetches from your remotes in the background so the commit graph and the ahead\u002Fbehind counts stay current without you asking. It ",[52,3217,3218],{},"only downloads"," — nothing is merged, checked out, reset, or deleted, and no branch is ever removed, so a fetch can never change your files or lose work.",[10,3221,3222],{},"Two speeds, because they answer different questions:",[331,3224,3225,3232],{},[334,3226,3227,3228,3231],{},"the project whose ",[52,3229,3230],{},"Git tab you have open"," is fetched about once a minute — that's where a stale count is on screen in front of you;",[334,3233,3234,3235,3238],{},"your ",[52,3236,3237],{},"other projects"," are fetched about every ten minutes, so their graphs are already right when you switch to them.",[10,3240,3241,3242,3245,3246,3248,3249,3252,3253,3255,3256,3258],{},"Fetching ",[52,3243,3244],{},"pauses while the Plexus window is hidden",", slows down while the window is in the background, and stands aside whenever a git operation of your own is running — it will never make one of your actions wait or fail. It also leaves your SSH setup alone: if you've configured your own ",[22,3247,1203],{}," command for git, background fetches use it exactly as your own commands do. A background fetch will ",[52,3250,3251],{},"never prompt you"," for anything — no password box, no key passphrase — so a remote that needs one is simply left for Refresh or Fetch all, where you're there to answer. A ",[99,3254,3166],{"href":3165}," is the exception that needs no answer from you: an ",[22,3257,1200],{}," remote on GitHub or Bitbucket authenticates with that connection in the background, exactly as it would on Refresh. If a fetch fails, Plexus says nothing: it backs off, keeps trying more slowly, and shows it on the freshness note rather than interrupting you.",[10,3260,3261,3262,3265,3266,3269,3270,3273,3274,3277,3278,132],{},"Because a fetch only downloads, it never moves your own branches: after one, ",[22,3263,3264],{},"origin\u002Fmain"," is current but your local ",[22,3267,3268],{},"main"," is exactly where you left it. That's the gap the New session dialog's pull toggle closes — ",[52,3271,3272],{},"Pull base branch first"," when the session cuts a new branch, ",[52,3275,3276],{},"Pull the branch first"," when it starts on an existing one — see ",[99,3279,3281],{"href":3280},"\u002Fdocs\u002Fsessions#pull-before-you-start","Pull before you start",[47,3283,3284],{},[10,3285,3286,3287,3289,3290,3293,3294,320,3297,132],{},"Turn it off for one project from the ",[52,3288,2997],{}," button's menu — ",[52,3291,3292],{},"Fetch automatically"," — or globally, along with both intervals, in ",[52,3295,3296],{},"Settings → Git & PRs",[99,3298,102],{"href":101},[14,3300,3302],{"id":3301},"search-the-history","Search the history",[10,3304,3305,3306,1432,3309,756,3312,3315],{},"The box above the commit graph finds commits by ",[52,3307,3308],{},"message",[52,3310,3311],{},"author name or email",[52,3313,3314],{},"commit id"," — a short prefix is enough. Results replace the graph with a plain list, newest first, and searching covers the whole repository rather than only the part of the history you've scrolled to.",[10,3317,3318,3319,3321,3322,3324],{},"The lane graph can't be drawn for a filtered set of commits — the lines between commits only mean something when their neighbours are present — so search deliberately shows a list instead. Clear the box (or press ",[52,3320,2750],{}," in it) to return to the graph exactly where you were. With the box already empty, ",[52,3323,2750],{}," does whatever it would normally do — closing a full-width diff, for instance — rather than being swallowed by the search field.",[14,3326,3328],{"id":3327},"stage-and-commit","Stage and commit",[10,3330,3331,3332,3334,3335,1432,3338,1439,3341,3344,3345,132],{},"Select ",[52,3333,2668],{}," (the pinned top row) to open the staging pane. Files group into ",[52,3336,3337],{},"Staged",[52,3339,3340],{},"Unstaged",[52,3342,3343],{},"Conflicted"," sections with per-file and per-section stage\u002Funstage buttons; clicking a file opens its working-tree diff in the ",[99,3346,3347],{"href":2477},"full-width view",[10,3349,3350,3351,2639,3354,3357],{},"Inside a diff, every hunk carries its own ",[52,3352,3353],{},"Stage hunk",[52,3355,3356],{},"Unstage hunk"," button, so you can split one file across several commits. Untracked files are the exception — they have no hunks yet and stage as a whole.",[105,3359,3361],{"id":3360},"discard-changes","Discard changes",[10,3363,3364],{},"There are three ways to throw work away, and all of them confirm first.",[10,3366,3367,3370,3371,3374,3375,3378,3379,3382,3383,3385,3386,3389,3390,3393,3394,3397],{},[52,3368,3369],{},"One or more files."," Right-click a changed file and choose ",[52,3372,3373],{},"Discard changes…",", or select files and use the header button. Selection works like a file manager: click to select, ",[52,3376,3377],{},"Ctrl\u002FCmd-click"," to toggle individual files, ",[52,3380,3381],{},"Shift-click"," to select a range; once something is selected the header's ",[52,3384,3138],{}," button is joined by ",[52,3387,3388],{},"Discard (N)",". Right-clicking a file that's already part of your selection acts on the whole selection — the menu entry says so, reading ",[52,3391,3392],{},"Discard 3 files…"," — while right-clicking outside it selects just that file first. Discard reverts modified and deleted files to the last commit and ",[52,3395,3396],{},"deletes new or untracked files from disk"," (there's no committed version to restore); the confirmation lists every affected path.",[10,3399,3400,3403,3404,3407],{},[52,3401,3402],{},"Everything at once."," With nothing selected, the header offers ",[52,3405,3406],{},"Discard all"," instead. It returns every tracked file to the last commit and, unless you turn the switch off in the dialog, deletes every new file from disk — including new files you've already staged, which have never been committed either. Empty folders left behind by those files go too.",[10,3409,3410,3413,3414,3417,3418,3421,3422,3424],{},[52,3411,3412],{},"A single hunk."," In the full-width diff, each hunk on the ",[91,3415,3416],{},"unstaged"," side carries a ",[52,3419,3420],{},"Discard hunk"," button next to ",[52,3423,3353],{},". It reverts just those lines and leaves the rest of the file — and anything you've already staged in it — untouched.",[47,3426,3427],{"tone":69},[10,3428,3429,3430,3432],{},"Discard can't be undone, and nothing is stashed on your behalf. If you might want the changes back, cancel and use ",[52,3431,3138],{}," instead — it's right next to the discard button and fully reversible.",[47,3434,3435],{},[10,3436,3437,3438,3441,3442,3445,3446,3449,3450,3452,3453,3456,3457,3461],{},"Files ignored by ",[22,3439,3440],{},".gitignore"," are ",[52,3443,3444],{},"never"," touched — not by Discard, not by Discard all, not behind any switch. That includes ",[22,3447,3448],{},"node_modules\u002F",", build output and local ",[22,3451,1458],{}," files. Since those never appear in the file list, a confirmation dialog couldn't show you what it was about to delete, so Plexus doesn't offer it at all; run ",[22,3454,3455],{},"git clean -xfd"," in the ",[99,3458,3460],{"href":3459},"#the-terminal-tab","Terminal tab"," if you really want that.",[10,3463,3464,3465,3467,3468,3471,3472,3475,3476,3478],{},"Discard is blocked while an agent session is running on the main checkout unless you confirm the override — the same guard as checkout and reset. ",[52,3466,3406],{}," additionally refuses while a merge, rebase, cherry-pick or revert is in progress: finish or abort it from the ",[99,3469,3470],{"href":2627},"conflict banner"," first. To discard a ",[91,3473,3474],{},"staged"," hunk, use ",[52,3477,3356],{}," and then discard it from the unstaged side, where you can see the combined result before confirming.",[10,3480,3481,3482,3485,3486,3489,3490,3493],{},"The composer below takes a summary and an optional description. The ",[52,3483,3484],{},"AI"," button drafts both from the staged diff (tune it with the ",[52,3487,3488],{},"AI commit message instructions"," setting under Settings → Git & PRs), and ",[52,3491,3492],{},"Commit"," lands the staged files.",[105,3495,3497],{"id":3496},"amend","Amend",[10,3499,3500,3501,3503],{},"The composer's ",[52,3502,3497],{}," switch rewrites the head commit instead of creating a new one: toggling it on prefills the message from the current head (unless you've already typed), and an amend may be message-only — no staged files required.",[47,3505,3506],{"tone":69},[10,3507,3508,3509,3511,3512,3514,3515,132],{},"Amending a commit that's already on the remote rewrites published history — the composer warns you when the head commit has been pushed, because the next push will be rejected as a non-fast-forward. Pushing then offers the ",[52,3510,3128],{}," confirm (",[22,3513,3132],{},") covered under ",[99,3516,3518],{"href":3517},"#the-toolbar","the toolbar",[14,3520,2914],{"id":3521},"context-menus",[10,3523,3524,3525,3527,3528,3531,3532,3534,3535,3538,3539,3541],{},"Right-click gives each surface its own menu. There are eight: branches, remotes, tags, stashes, and worktrees in the ",[99,3526,2461],{"href":2535},", commits in the ",[99,3529,3530],{"href":2837},"graph",", and changed files in the ",[99,3533,2673],{"href":2672}," — and the branch and tag menus follow their ",[52,3536,3537],{},"labels into the graph",", folded refs in the ",[22,3540,2539],{}," panel included, so a right-click on a ref offers the same actions wherever you find it. On a commit row, the ref labels take the right-click and the rest of the row opens the commit menu.",[10,3543,3544,3545,3547,3548,3550,3551,3554,3555,3559],{},"Entries spell out what they will act on — \"Merge into ",[22,3546,3268],{},"…\", \"Delete from ",[22,3549,2783],{},"…\" — so the labels below stand in ",[22,3552,3553],{},"\u003Cplaceholders>"," for the part that varies. Anything that acts on the checked-out branch is greyed out when there isn't one, on a ",[99,3556,3558],{"href":3557},"#detached-head","detached HEAD",", and destructive entries always confirm before running.",[10,3561,3562,3565,3566,3569,3570,3573,3574,3577,3578,3580,3581,3584],{},[52,3563,3564],{},"Local branches"," — \"Checkout ",[22,3567,3568],{},"\u003Cbranch>","\" · \"Create branch here…\" · \"Pull\" (only on the branch you're on, and only with an upstream) · \"Fast-forward to ",[22,3571,3572],{},"\u003Cupstream>","\" · \"Push\" · \"Merge into ",[22,3575,3576],{},"\u003Ccurrent>","…\" · \"Rebase ",[22,3579,3576],{}," onto this…\" · \"Set upstream…\" · \"Rename…\" · ",[52,3582,3583],{},"Delete"," → \"Delete local…\", \"Delete remote only…\", \"Delete local and remote…\" · \"Copy branch name\" \u002F \"Copy sha\" · \"Create tag here…\".",[331,3586,3587,3603,3613],{},[334,3588,3589,3595,3596,3599,3600,3602],{},[52,3590,3591,3592,3594],{},"\"Fast-forward to ",[22,3593,3572],{},"\""," catches a branch up to its remote ",[52,3597,3598],{},"without checking it out"," and without touching your working tree — so you can bring ",[22,3601,3268],{}," up to date while you keep working on your feature branch. It appears when the branch has an upstream and is behind it, and it only fast-forwards: a branch that has diverged is left alone.",[334,3604,3605,3608,3609,3612],{},[52,3606,3607],{},"\"Delete remote only…\""," deletes the branch on the remote and keeps yours — the usual tidy-up after a merged pull request. It's available on the branch you're currently on, too; only ",[91,3610,3611],{},"local"," deletion needs you to be somewhere else first.",[334,3614,3615],{},"Deleting or renaming a branch that belongs to a session warns you first, naming the session.",[10,3617,3618,3621,3622,3624,3625,3577,3627,3629,3630,3633,3634,3637],{},[52,3619,3620],{},"Remote branches"," — \"Checkout as local branch\" (creating the local tracking branch, or switching to an existing one and fast-forwarding it to the remote) · \"Create branch here…\" · \"Fast-forward ",[22,3623,3576],{}," to this\" (offered when it's the current branch's upstream) · \"Merge into ",[22,3626,3576],{},[22,3628,3576],{}," onto this…\" · \"Delete from ",[22,3631,3632],{},"\u003Cremote>","…\" · \"Copy branch name\" (the full ",[22,3635,3636],{},"origin\u002F…"," name — what you'd paste into a git command) \u002F \"Copy sha\" · \"Create tag here…\".",[10,3639,3640,3642,3643,3646,3647,132],{},[52,3641,2918],{}," — on a remote's ",[52,3644,3645],{},"section header",", not on the branches under it: \"Edit remote…\" · \"Add remote…\" · \"Remove remote…\" · \"Copy URL\" (what the header shows — a credential stored in the URL is never copied along) \u002F \"Copy remote name\". See ",[99,3648,2918],{"href":2787},[10,3650,3651,3654,3655,3657,3658,2639,3660,2639,3662,3664,3665,3668],{},[52,3652,3653],{},"Commit rows"," — \"Checkout commit\" (detaches HEAD) · \"Create branch here…\" · \"Create tag here…\" · \"Cherry-pick commit\" · \"Revert commit\" · \"Reset ",[22,3656,3576],{}," to this commit\" (",[52,3659,2638],{},[52,3661,2642],{},[52,3663,2645],{}," — a hard reset discards work, so it demands a typed confirmation) · \"Copy sha\" \u002F \"Copy short sha\" \u002F \"Copy subject\" \u002F \"Copy message\" (subject ",[52,3666,3667],{},"and"," body, the way git writes it).",[10,3670,3671,3673,3674,3676,3677,3679],{},[52,3672,2797],{}," — \"Create branch here…\" · \"Checkout tag\" (detaches HEAD) · \"Push to ",[22,3675,3632],{},"\", one entry per remote · \"Copy tag name\" \u002F \"Copy sha\" · \"Delete tag locally…\" · \"Delete from ",[22,3678,3632],{},"…\", again one per remote. The two deletions are deliberately separate: the local one only affects this checkout, while deleting from a remote removes the tag for everyone who fetches it.",[10,3681,3682,3684],{},[52,3683,2794],{}," — \"Create branch from stash…\" · \"Apply\" · \"Pop\" · \"Copy message\" · \"Drop…\".",[331,3686,3687,3693],{},[334,3688,3689,3692],{},[52,3690,3691],{},"\"Create branch from stash…\""," asks for a name, then creates that branch where the stash was made, checks it out, applies the stash into it, and drops the entry — the clean way out of a stash that no longer fits the branch you're on.",[334,3694,3695,1055,3697,3699,3700,3703],{},[52,3696,2888],{},[52,3698,2891],{}," are the same actions as the row's hover buttons. ",[52,3701,3702],{},"\"Drop…\""," is not: the menu entry opens a confirmation dialog naming the stash, while the hover button keeps its quicker two-step click.",[10,3705,3706,3709,3710,3713],{},[52,3707,3708],{},"Changed files"," — \"Stage file\" or \"Unstage file\", whichever side the file is on · \"Copy path\" \u002F \"Copy file name\" · ",[52,3711,3712],{},"\"Discard changes…\"",". On a conflicted file the staging entries give way to \"Take ours (whole file)\" \u002F \"Take theirs (whole file)\", and discard is greyed out — resolve it first, or discard the whole file from the header.",[331,3715,3716],{},[334,3717,3718,3719,3722,3723,3726],{},"The two halves of the menu answer to different things, which the labels spell out: staging always acts on the ",[52,3720,3721],{},"one file you right-clicked",", while discard acts on your whole ",[52,3724,3725],{},"selection"," — so with three files selected the entry reads \"Discard 3 files…\" next to a plain \"Stage file\".",[10,3728,3729,3731],{},[52,3730,1463],{}," — \"Copy path\" · \"Remove worktree…\" · \"Prune stale worktree entries…\".",[331,3733,3734,3757],{},[334,3735,3736,3739,3740,3743,3744,3746,3747,3749,3750,3753,3754,3756],{},[52,3737,3738],{},"\"Remove worktree…\""," deletes the worktree's folder from disk and clears git's record of it, which releases the branch it was holding. The dialog offers to delete that branch too (off by default). That branch delete is the safe kind: if the branch still carries commits that aren't merged anywhere, git keeps it and Plexus tells you — the worktree is gone by then, so the follow-up dialog offers to delete just the branch, spelling out that its commits go with it. The repository's main checkout can't be removed here, and neither can a worktree with a ",[52,3741,3742],{},"running"," session in it — stop that session first, even if that session belongs to another project on the same repository. A session that is in the middle of starting or stopping is refused the same way; try again once it settles. Removing one that belongs to a stopped session asks you to confirm, naming the session. An ",[52,3745,2862],{}," session's worktree removes without that extra confirmation — reclaiming those leftovers is what this section is for — but the dialog says whose it is and warns that restoring that session will no longer be able to resume it. Either way the session stops pointing at the folder you just removed, so it offers a fresh ",[52,3748,1307],{}," rather than a ",[52,3751,3752],{},"Resume"," that could only fail.",[1124,3755],{},"Two things can stand in the way of a removal, and each gets its own confirmation: a folder that belongs to a stopped session, and a folder with uncommitted or untracked work in it. Confirming one never waives the other — if both apply, you'll be asked twice, once in each set of words.",[334,3758,3759,3762,3763,3766,3767,3769],{},[52,3760,3761],{},"\"Prune stale worktree entries…\""," is repo-wide and touches nothing on disk. It only clears git's records for worktree folders that are already gone, and it tells you how many it cleared. The confirmation lists every record it will clear. ",[52,3764,3765],{},"Locked"," entries are left out of that list: a lock is how git marks a worktree that lives on removable or network storage and is only temporarily missing, so clearing one is a separate switch in the dialog — and the toast says how many locked entries it kept. Like Remove, it also stops any session that still pointed at a pruned folder from offering a ",[52,3768,3752],{}," into it.",[105,3771,2878],{"id":3772},"when-a-branch-is-locked-to-a-worktree",[10,3774,3775,3776,3779],{},"git refuses to delete or check out a branch that is checked out ",[52,3777,3778],{},"in any worktree"," — including one whose folder has been deleted behind git's back. That second case is the confusing one: git names a path that no longer exists, so there's nothing to go and look at.",[47,3781,3782],{"tone":69},[10,3783,3784,3785,3788,3789,3791,3792,3794,3795,3797,3798,3800,3801,3803,3804,502],{},"If deleting or checking out a branch fails with ",[91,3786,3787],{},"\"already checked out at …\"",", look for that path in the ",[52,3790,1463],{}," section. A row badged ",[52,3793,2866],{}," means only git's record survives — use ",[52,3796,3761],{}," to clear it (if that row is also badged ",[52,3799,2870],{},", turn on the dialog's switch for locked entries). A row that's still really there needs ",[52,3802,3738],{}," instead (or, if a session owns it, ",[99,3805,3807],{"href":3806},"\u002Fdocs\u002Fsessions#archive-vs-remove","remove that session",[10,3809,3810],{},"Plexus clears its own leftovers automatically: on startup it drops the records for any worktree it created that has since disappeared. It deliberately leaves worktrees you made yourself alone, even when their folder is missing — a worktree on an unplugged drive looks exactly the same, and cleaning it up is your call, not the app's.",[105,3812,3814],{"id":3813},"detached-head","Detached HEAD",[10,3816,3817,3818,3820,3821,3823],{},"\"Checkout commit\" and \"Checkout tag\" leave you on a ",[52,3819,3558],{}," — you're looking at that exact snapshot, with no branch to record new commits on (a commit isn't a branch, and neither is a tag, so there's nothing for further commits to advance). The branch switcher shows the short commit id with a ",[22,3822,3071],{}," badge, and everything that acts on the current branch — Pull, Push, merge, rebase, reset, cherry-pick, revert — greys out until you check a branch out again.",[47,3825,3826],{"tone":69},[10,3827,3828,3829,3832],{},"Detaching costs you nothing: your branches stay exactly where they are, and checking one out puts you straight back. But a commit you make while detached belongs to no branch and is easy to lose sight of — use ",[52,3830,3831],{},"Create branch here…"," on the commit or tag instead if you mean to build on it.",[14,3834,3836],{"id":3835},"conflict-resolution","Conflict resolution",[10,3838,3839],{},"A merge, rebase, cherry-pick, revert, pull, or stash pop that hits conflicts doesn't fail — the tab switches into conflict mode and lets you resolve everything in place.",[10,3841,3842,3843,3846],{},"An amber ",[52,3844,3845],{},"banner"," appears under the toolbar naming the operation and counting the conflicted files remaining. While it's up, the toolbar and branch switcher are disabled and the view stays on your uncommitted changes, where conflicted files are listed in their own section.",[10,3848,3849],{},"Each conflicted file offers three ways out:",[331,3851,3852,3861,3895],{},[334,3853,3854,2639,3857,3860],{},[52,3855,3856],{},"Ours",[52,3858,3859],{},"Theirs"," on the file row — take one side whole, no questions asked. (Binary or very large files resolve this way only.)",[334,3862,3863,3866,3867,3869,3870,1055,3873,3876,3877,1432,3880,756,3883,3886,3887,3890,3891,3894],{},[52,3864,3865],{},"Hunk picker"," — click the file and its resolve pane opens in the ",[99,3868,3347],{"href":2477},", each conflict shown as side-by-side ",[91,3871,3872],{},"ours",[91,3874,3875],{},"theirs"," cards, labeled with where each side came from. Pick ",[52,3878,3879],{},"Take ours",[52,3881,3882],{},"Take theirs",[52,3884,3885],{},"Take both"," per conflict; once every conflict has a choice, ",[52,3888,3889],{},"Apply resolution"," writes the file, and the default-on ",[52,3892,3893],{},"Mark resolved after applying"," switch stages it in the same step.",[334,3896,3897,3900,3901,132],{},[52,3898,3899],{},"Edit file"," — switch the picker to a full editor to resolve the markers by hand, then ",[52,3902,3903],{},"Save & mark resolved",[10,3905,3906,3907,1432,3910,1432,3913,1432,3916,756,3919,3922,3923,3926],{},"When no conflicted files remain, the banner's action button finishes the operation — ",[52,3908,3909],{},"Commit merge",[52,3911,3912],{},"Continue rebase",[52,3914,3915],{},"Continue cherry-pick",[52,3917,3918],{},"Continue revert",[52,3920,3921],{},"Done"," for a stash pop (which then drops the now-applied stash). A rebase that spans several commits may stop again on the next conflict; the banner simply stays up with the new file list. ",[52,3924,3925],{},"Abort"," (with a confirmation) backs the whole operation out and restores your working tree — a popped stash survives an abort.",[47,3928,3929],{},[10,3930,3931,3932,3934],{},"A conflicting stash ",[52,3933,2888],{}," is the one case with nothing to continue or abort: the stash is kept either way, so there's no banner — just resolve the conflicted files and stage them, and you're done.",[14,3936,3938],{"id":3937},"the-busy-checkout-guard","The busy-checkout guard",[10,3940,3941,3942,3945,3946,3949],{},"Sessions ",[99,3943,3944],{"href":1293},"started on the root tree"," run their agent directly in the same checkout this tab operates on. If such a session's agent is running, any operation that would change the working tree — checkout, pull, merge, rebase, reset, revert, cherry-pick, stash apply\u002Fpop, and continuing or aborting a conflict — is stopped first with an ",[52,3947,3948],{},"\"An agent session is running on this checkout\""," dialog naming the session.",[10,3951,3952,3953,3955,3956,3959],{},"That's a guard, not a wall: ",[52,3954,1186],{}," leaves everything untouched, while ",[52,3957,3958],{},"Continue anyway"," runs the operation regardless — do that only when you're sure the agent won't trip over files changing underneath it. Operations that never touch the working tree — fetch, push, staging, committing, and tag work — are never blocked.",[14,3961,3963],{"id":3962},"the-terminal-tab","The Terminal tab",[10,3965,3966,3967,3970,3971,132],{},"The Terminal tab opens plain shell terminals rooted in the ",[52,3968,3969],{},"project's root directory"," — the same primary checkout the Git tab operates on, never a session worktree. The shells are kept warm in the background, so a dev server or watcher you start here keeps running as you move around the app; add, close, and rename tabs the same way as the session's bottom terminal. See ",[99,3972,3974],{"href":3973},"\u002Fdocs\u002Fproject-terminal","Project Terminal",[14,3976,2343],{"id":2342},[331,3978,3979,3984,3990,3998,4003,4013],{},[334,3980,3981,3983],{},[99,3982,3974],{"href":3973}," — root-level shells on the project's main checkout.",[334,3985,3986,3989],{},[99,3987,3988],{"href":368},"Session Git"," — the per-session git tab for a worktree branch.",[334,3991,3992,3994,3995,3997],{},[99,3993,2655],{"href":1469}," — how Plexus tracks a session's PR, and what changing ",[22,3996,2783],{}," resets.",[334,3999,4000,4002],{},[99,4001,1358],{"href":1357}," — the global session table; the project view scopes it down.",[334,4004,4005,4007,4008,1432,4010,4012],{},[99,4006,102],{"href":101}," — ",[52,4009,3084],{},[52,4011,2699],{},", and the AI commit prompt.",[334,4014,4015,4017],{},[99,4016,2000],{"href":1476}," — the project tab bindings.",{"title":33,"searchDepth":266,"depth":266,"links":4019},[4020,4021,4022,4023,4026,4027,4028,4029,4032,4033,4037,4041,4042,4043,4044],{"id":2402,"depth":266,"text":2403},{"id":2437,"depth":266,"text":2438},{"id":2454,"depth":266,"text":2455},{"id":2489,"depth":266,"text":2490,"children":4024},[4025],{"id":2681,"depth":271,"text":2682},{"id":2708,"depth":266,"text":2478},{"id":2768,"depth":266,"text":2769},{"id":2917,"depth":266,"text":2918},{"id":3059,"depth":266,"text":3060,"children":4030},[4031],{"id":3211,"depth":271,"text":3212},{"id":3301,"depth":266,"text":3302},{"id":3327,"depth":266,"text":3328,"children":4034},[4035,4036],{"id":3360,"depth":271,"text":3361},{"id":3496,"depth":271,"text":3497},{"id":3521,"depth":266,"text":2914,"children":4038},[4039,4040],{"id":3772,"depth":271,"text":2878},{"id":3813,"depth":271,"text":3814},{"id":3835,"depth":266,"text":3836},{"id":3937,"depth":266,"text":3938},{"id":3962,"depth":266,"text":3963},{"id":2342,"depth":266,"text":2343},"A full git client on the project's main checkout — commit graph, branches, staging, and conflict resolution.","GitGraph",{},"Git GUI",11,{"title":2381,"description":4045},"docs\u002Fproject-git","0WukabmiMrWXJPdDW5dN051VPZZH1w0n7IrJyOmqXv4",{"id":4054,"title":3974,"body":4055,"description":4212,"extension":277,"group":2372,"icon":4213,"meta":4214,"navTitle":4062,"navigation":281,"order":4215,"path":3973,"seo":4216,"stem":4217,"__hash__":4218},"docs\u002Fdocs\u002Fproject-terminal.md",{"type":7,"value":4056,"toc":4206},[4057,4070,4074,4101,4103,4112,4116,4119,4139,4150,4154,4160,4167,4182,4184],[10,4058,4059,4060,4063,4064,4067,4068,2399],{},"The project view's ",[52,4061,4062],{},"Terminal"," tab opens plain shell terminals rooted in the project's ",[52,4065,4066],{},"root directory"," — the folder you registered as the project, its primary checkout — kept running in the background so a dev server, watcher, or build you start here keeps going wherever you navigate. Throughout this page ",[22,4069,1996],{},[14,4071,4073],{"id":4072},"open-the-terminal-tab","Open the Terminal tab",[10,4075,2406,4076,4078,4079,4082,4083,4085,4086,4089,4090,630,4092,4094,4095,630,4097,4100],{},[52,4077,2409],{}," in the left sidebar to open the ",[99,4080,1611],{"href":4081},"\u002Fdocs\u002Fproject-git#open-the-project-view",", then pick the ",[52,4084,4062],{}," tab — or press ",[22,4087,4088],{},"⌘3"," from anywhere in the project view. It's the third tab, alongside ",[52,4091,1358],{},[22,4093,1977],{},") and ",[52,4096,136],{},[22,4098,4099],{},"⌘2","):",[1365,4102],{":rows":2427},[10,4104,4105,4106,4109,4110,2434],{},"The first shell spawns automatically the moment you open the tab. These bindings share their default combos with the ",[99,4107,4108],{"href":1476},"session tab shortcuts"," — a session and a project are never in view at the same time, so they don't conflict, and each is ",[99,4111,2433],{"href":1476},[14,4113,4115],{"id":4114},"run-multiple-terminals","Run multiple terminals",[10,4117,4118],{},"The tab is a tab strip, so you can keep several shells open at once — each an independent login shell with its own scrollback, started in the project root:",[331,4120,4121,4127,4133],{},[334,4122,4123,4124,4126],{},"Click ",[22,4125,1903],{}," to add a new terminal.",[334,4128,4129,4132],{},[52,4130,4131],{},"Double-click"," a tab to rename it inline.",[334,4134,4135,4136,4138],{},"Click the ",[22,4137,2423],{}," on a tab to close that shell.",[10,4140,4141,4142,4145,4146,132],{},"Use them for whatever runs at the repository root: start the dev server, run a file watcher, kick off a build, or tail logs while your sessions work in their own worktrees. Which shell Plexus spawns follows the global ",[52,4143,4144],{},"Terminal shell"," setting (Settings → Advanced) — see ",[99,4147,4149],{"href":4148},"\u002Fdocs\u002Fterminal#choose-which-shell-to-run","Choose which shell to run",[14,4151,4153],{"id":4152},"keep-warm-behavior","Keep-warm behavior",[10,4155,4156,4157,4159],{},"These terminals belong to the ",[52,4158,1602],{},", not to any one tab or session. Switching tabs, opening a session, or moving to another project leaves them running in the background — nothing in flight is interrupted, and returning to the Terminal tab re-attaches you to the full scrollback. That makes the project Terminal the right home for a long-running root process like a dev server, watcher, or build.",[10,4161,4162,4163,4166],{},"They're only torn down when the ",[52,4164,4165],{},"project itself is deleted or archived"," — closing the project view or navigating away never kills them.",[47,4168,4169],{},[10,4170,4171,4173,4174,4176,4177,4179,4180,132],{},[22,4172,1996],{}," means Cmd on macOS and Ctrl on Windows\u002FLinux. Rebind the tab shortcut under Keybindings in ",[99,4175,102],{"href":101},"; see ",[99,4178,2000],{"href":1476},". For a shell scoped to a single session's worktree instead of the project root, see the session ",[99,4181,4062],{"href":1969},[14,4183,2343],{"id":2342},[331,4185,4186,4192,4197,4202],{},[334,4187,4188,4191],{},[99,4189,4190],{"href":1969},"Session Terminal"," — the per-session bottom shells, rooted in a session's worktree.",[334,4193,4194,4196],{},[99,4195,2381],{"href":373}," — the project view's Git tab.",[334,4198,4199,4201],{},[99,4200,1358],{"href":1357}," — the project view's session table.",[334,4203,4204,4017],{},[99,4205,2000],{"href":1476},{"title":33,"searchDepth":266,"depth":266,"links":4207},[4208,4209,4210,4211],{"id":4072,"depth":266,"text":4073},{"id":4114,"depth":266,"text":4115},{"id":4152,"depth":266,"text":4153},{"id":2342,"depth":266,"text":2343},"Plain shell terminals rooted in the project's root directory — kept warm in the background, with renameable tabs.","MonitorDot",{},12,{"title":3974,"description":4212},"docs\u002Fproject-terminal","WJOLJFNDumViVsHXjrfHI_ImwCfT7YF5xvCAxlk2wxA",{"id":4220,"title":1270,"body":4221,"description":5018,"extension":277,"group":5019,"icon":5020,"meta":5021,"navTitle":312,"navigation":281,"order":5022,"path":1293,"seo":5023,"stem":5024,"__hash__":5025},"docs\u002Fdocs\u002Fsessions.md",{"type":7,"value":4222,"toc":5000},[4223,4226,4230,4250,4254,4262,4272,4275,4282,4291,4294,4305,4311,4314,4325,4351,4370,4373,4383,4412,4425,4437,4440,4453,4456,4482,4489,4495,4521,4524,4536,4540,4543,4546,4555,4559,4590,4609,4618,4631,4643,4649,4653,4672,4675,4679,4686,4700,4707,4712,4722,4726,4732,4780,4791,4806,4842,4853,4886,4902,4906,4916,4960,4970],[10,4224,4225],{},"A session is one named Claude Code agent running in its own git worktree, on a branch it either cuts for you or checks out — the atomic unit of work in Plexus.",[14,4227,4229],{"id":4228},"creating-a-session","Creating a session",[10,4231,490,4232,4234,4235,4237,4238,4240,4241,4243,4244,4246,4247,132],{},[22,4233,1083],{}," menu on a project row in the tree and choose ",[52,4236,2296],{},", or press the ",[52,4239,1903],{}," in the app bar. Give it a name (required), then pick how the session gets its branch — ",[52,4242,1261],{},", the default, or ",[52,4245,1265],{}," — fill in that mode's fields, and click ",[52,4248,4249],{},"Create",[105,4251,4253],{"id":4252},"which-project-it-lands-in","Which project it lands in",[10,4255,4256,4258,4259,4261],{},[52,4257,304],{}," is the dialog's own field, prefilled from wherever you opened it: the row you used, or — from the app bar's ",[52,4260,1903],{}," — the project you have open. Change it there rather than closing the dialog and starting again.",[10,4263,4264,4265,4268,4269,4271],{},"It offers the same projects the sidebar shows: the current workspace's, or every workspace's grouped by name if you have set ",[52,4266,4267],{},"Workspace navigation"," to \"All workspaces in the sidebar\" (see ",[99,4270,102],{"href":101},"). If the dialog was opened on a project in another workspace — from a dashboard row, say — both workspaces are listed under their names, so you can still get back.",[10,4273,4274],{},"Switching project re-reads that repository's branches, so the base branch and any branch you had picked are cleared — a branch name means nothing in a different repository. The name you typed is kept; a name Plexus filled in for you from a branch is not.",[10,4276,4277,4278,4281],{},"Whichever mode you use, the rest of the session is identical: the same worktree location, the same ",[99,4279,4280],{"href":388},"create, run, and teardown hooks",", and the same Agent, Review, Explorer, and Git tabs.",[10,4283,4284,4285,4287,4288,4290],{},"Two sessions in the same project can share a display name; it's the branch that has to be unique. In ",[52,4286,1261],{}," mode Plexus guarantees that with a suffix, and in ",[52,4289,1265],{}," mode git does — a branch can only be checked out in one worktree at a time.",[105,4292,1261],{"id":4293},"new-branch",[10,4295,4296,4297,4300,4301,4304],{},"The default, and the classic Plexus flow. Pick a ",[52,4298,4299],{},"base branch"," — Plexus preselects the branch currently checked out in the project's main working copy (or a fixed default you pin per project with the ",[52,4302,4303],{},"Default base branch"," setting in Settings → Worktrees & Hooks) and lists both local and remote branches.",[10,4306,4307,4308,4310],{},"When the session starts, Plexus cuts a fresh git worktree, branches a new ",[22,4309,1655],{}," branch off the base (deduplicated if that name is taken), and mints a named Claude Code conversation inside it. The session owns that branch for its lifetime, so any number of sessions per project run independently without stepping on each other's files.",[105,4312,1265],{"id":4313},"existing-branch",[10,4315,4316,4317,4319,4320,4324],{},"Switch the dialog to ",[52,4318,1265],{}," when the branch already exists — to carry on a branch a colleague pushed, or to spin a session up purely to ",[99,4321,4323],{"href":4322},"\u002Fdocs\u002Freview#reviewing-someone-elses-branch","review one",". There are two fields:",[331,4326,4327,4332],{},[334,4328,4329,4331],{},[52,4330,2123],{}," — the branch to check out into the session's worktree. Branches that exist only on your remote are listed alongside local ones.",[334,4333,4334,4337,4338,4341,4342,4345,4346,2789,4348,4350],{},[52,4335,4336],{},"Compare with"," — the base the session is measured against. It defaults to the repository's ",[52,4339,4340],{},"trunk"," (whatever ",[22,4343,4344],{},"origin\u002FHEAD"," points at — usually ",[22,4347,3268],{},[91,4349,168],{}," to the branch checked out in your main working copy, because a branch you didn't cut from that checkout has no particular relationship to it.",[10,4352,4353,4354,4356,4357,3456,4360,4363,4364,4366,4367,4369],{},"The base is never checked out by the session; it is the ref everything compares against. The ",[99,4355,359],{"href":358}," tab diffs the branch against it, ",[52,4358,4359],{},"Rebase onto…",[99,4361,369],{"href":4362},"\u002Fdocs\u002Fgit#branch-operations"," targets it, and a ",[99,4365,1470],{"href":1469}," opened from the session uses it as its base — so pick the branch you intend to merge into. A project's ",[52,4368,4303],{}," setting overrides the default in both modes.",[10,4371,4372],{},"Plexus creates the worktree and checks the branch out into it; it does not create, rename, or move the branch itself.",[10,4374,4375,4378,4379,4382],{},[52,4376,4377],{},"Some branches can't be picked."," git allows a branch to be checked out in exactly ",[52,4380,4381],{},"one"," worktree at a time, so a branch that's already checked out somewhere is still listed, but unavailable — with the reason:",[331,4384,4385,4391,4398],{},[334,4386,4387,4388,4390],{},"another ",[52,4389,1641],{}," has it — open that session, or remove it first;",[334,4392,4393,4394,4397],{},"your project's own ",[52,4395,4396],{},"working copy"," is on it — switch that checkout to another branch;",[334,4399,4400,4401,4404,4405,4408,4409,132],{},"a worktree that no longer exists still holds git's ",[52,4402,4403],{},"record"," of it — clear that one with ",[52,4406,4407],{},"Prune stale worktree entries…"," in the project ",[99,4410,369],{"href":4411},"\u002Fdocs\u002Fproject-git#when-a-branch-is-locked-to-a-worktree",[10,4413,4414,4417,4418,4421,4422,4424],{},[52,4415,4416],{},"A branch that lives only on the remote"," becomes a real local branch tracking ",[22,4419,4420],{},"origin\u002F\u003Cname>",", rather than a detached snapshot. The session starts at the remote's tip, and ahead\u002Fbehind counts, ",[52,4423,2576],{},", and pull requests all behave exactly as they would on a branch you created yourself.",[47,4426,4427],{"tone":69},[10,4428,4429,4430,4433,4434,4436],{},"Rebase and squash rewrite history. On a branch someone else also has, that's a rewrite of shared history — see ",[99,4431,4432],{"href":4362},"Git workflow",". Plexus warns rather than stops you, and its ",[52,4435,2576],{}," is never a force-push, so a rewrite stays on your machine until you deal with it deliberately.",[105,4438,3281],{"id":4439},"pull-before-you-start",[10,4441,4442,4443,4446,4447,4449,4450,4452],{},"The worktree is cut from ",[52,4444,4445],{},"your local copy"," of the branch it starts from. Background fetching keeps Plexus's picture of the remote current, but it never moves your own branches — so if your local ",[22,4448,3268],{}," is a few days behind, a new session off ",[22,4451,3268],{}," starts a few days behind too, and you find out at pull-request time. The same goes for an existing branch that's been pushed to since you last pulled it.",[10,4454,4455],{},"One toggle in the New session dialog closes that gap, and it follows the mode you're in:",[331,4457,4458,4471],{},[334,4459,4460,4461,4463,4464,4466,4467,4470],{},"In ",[52,4462,1261],{}," mode it reads ",[52,4465,3272],{}," and fetches, then fast-forwards, the ",[52,4468,4469],{},"base"," before the session is created.",[334,4472,4460,4473,4463,4475,4477,4478,4481],{},[52,4474,1265],{},[52,4476,3276],{}," and does the same for the ",[52,4479,4480],{},"branch you picked",", so the worktree starts at the remote's tip instead of your older copy. The base is left alone.",[10,4483,4484,4485,4488],{},"Plexus remembers the toggle for next time. It does nothing when there's nothing to pull — a branch with no remote copy, one that's already current, or one that is merely ",[52,4486,4487],{},"ahead"," of the remote because you have commits you haven't pushed yet. That last case is left alone deliberately: there's nothing to catch up on, so the session is created normally.",[10,4490,4491,4492,4494],{},"Picking a branch from the ",[52,4493,3620],{}," group is the same story from the other side: you have no local copy of it yet, so the fetch is the whole job — Plexus creates your local branch from the freshly fetched remote one, which is already at the remote's tip. The toggle simply makes sure that fetch is fresh.",[47,4496,4497],{"tone":69},[10,4498,4499,4500,4502,4503,4505,4506,4509,4510,4513,4514,4516,4517,4520],{},"This is a real pull, so it can move files. If the branch being pulled is the one checked out in your project's main working copy — which only happens for a base in ",[52,4501,1261],{}," mode, since a branch that's already checked out can't be picked in ",[52,4504,1265],{}," mode — fast-forwarding it updates that working copy. And if it ",[52,4507,4508],{},"can't"," be fast-forwarded — you're offline, the working copy has uncommitted changes, a root-tree session is running on it, or the branch has ",[52,4511,4512],{},"diverged"," (it has unpushed commits ",[91,4515,3667],{}," the remote has new ones) — the session is ",[52,4518,4519],{},"not created",". The dialog stays open and tells you why, so you can fix it or untick the toggle and create the session from your local copy.",[105,4522,1284],{"id":4523},"start-session-on-root-tree",[10,4525,4526,4527,4529,4530,4532,4533,132],{},"When you just want a quick edit or review without a separate worktree, open the project's ",[22,4528,1083],{}," menu and choose ",[52,4531,1284],{},". There's no base-branch picker — the session runs directly in the project's root working tree and launches immediately. Because root-tree sessions share that one working directory, use them for fast, throwaway work and reach for a standard session when you want isolation. More on layout in ",[99,4534,4535],{"href":1462},"Worktrees & environment",[14,4537,4539],{"id":4538},"lifecycle","Lifecycle",[10,4541,4542],{},"A session is just metadata until you start it. The agent process is killed when you stop it, but the worktree, branch, and conversation persist — so a stopped session is always resumable.",[1365,4544],{":rows":4545},"[[\"Start\",\"Cut the worktree, run create + run hooks, and launch the agent — on a newly cut branch or on the existing one you picked.\"],[\"Resume\",\"Reattach the same conversation to a stopped session and pick up where it left off.\"],[\"Stop\",\"End the agent process but keep the worktree, branch, and transcript intact.\"],[\"Archive\",\"Hide the session in the archived drawer, fully restorable, nothing removed from disk.\"]]",[10,4547,4548,4549,4551,4552,4554],{},"By default a standard session launches the moment it's created — ",[52,4550,1316],{}," (Settings → Agent) defaults to on. Turn it off (project, workspace, or global scope) to have new sessions wait for you to click ",[52,4553,1307],{},". Root-tree sessions always launch on create.",[105,4556,4558],{"id":4557},"start-stop-resume","Start, stop, resume",[10,4560,4561,4562,3456,4564,4566,4567,4570,4571,1432,4574,4577,4578,4581,4582,4585,4586,4589],{},"Select a session and click ",[52,4563,1307],{},[99,4565,1303],{"href":1430}," tab. A ",[52,4568,4569],{},"Starting…"," spinner shows the live stage — ",[91,4572,4573],{},"Creating worktree…",[91,4575,4576],{},"Running \u003Chook>…",", then ",[91,4579,4580],{},"Starting agent…"," — before the terminal takes over. Click ",[52,4583,4584],{},"Stop"," to end the agent; if Claude Code exits on its own (you run ",[22,4587,4588],{},"\u002Fexit",", or it crashes), the session drops to stopped automatically.",[10,4591,4592,4594,4595,2639,4597,4599,4600,4603,4604,4608],{},[52,4593,1186],{}," sits under the spinner from the moment a start begins, so you are never stuck watching it. Cancelling stops whatever step is in flight and cleans up after it — the half-created worktree is removed, and the session returns to ",[52,4596,1307],{},[52,4598,3752],{},". The branch goes with it only if ",[52,4601,4602],{},"Plexus cut it",": a branch that already existed before the session is left exactly as it was. That rule holds for every way a start can fall over — a cancel, a ",[99,4605,4607],{"href":4606},"\u002Fdocs\u002Fhooks#aborting-on-failure","create hook"," that aborts the launch, or an agent that fails to spawn — so Plexus never deletes a branch it didn't create without asking. A session running on the project's own checkout has no separate worktree, and cancelling one never touches your repository.",[10,4610,4611,4612,4614,4615,4617],{},"If a start goes quiet for a minute, Plexus says so and offers ",[52,4613,4584],{}," as well. It does ",[91,4616,168],{}," give up on its own: the first checkout of a large repository can legitimately take a while, so the decision stays yours. The elapsed time is shown so you can judge it.",[10,4619,4123,4620,4622,4623,4626,4627,4630],{},[52,4621,3752],{}," to restart a stopped session. Plexus verifies the worktree still exists, re-runs your ",[22,4624,4625],{},"run"," hooks, and reattaches the ",[52,4628,4629],{},"same"," conversation — your prior transcript and context are intact.",[47,4632,4633],{},[10,4634,4635,4636,4639,4640,4642],{},"Sessions survive closing and reopening Plexus. Live agents don't, so on launch every previously running session is reconciled to ",[52,4637,4638],{},"stopped"," — but its pinned conversation id is kept, so the next ",[52,4641,3752],{}," reattaches exactly as if the app never closed.",[10,4644,4645,4646,4648],{},"The colored dot on each tree row tells you what needs you — working, waiting, or idle. See ",[99,4647,2139],{"href":348}," for the full breakdown.",[14,4650,4652],{"id":4651},"session-summary","Session summary",[10,4654,4655,4656,4659,4660,4663,4664,4667,4668,4671],{},"Every session's context bar carries a ",[52,4657,4658],{},"Summary"," button, next to ",[52,4661,4662],{},"Close session",". It opens a panel beside the tabs holding an AI-written recap of that session: a one-line ",[52,4665,4666],{},"What was asked",", then a short ",[52,4669,4670],{},"What's been done"," list of the concrete progress and where things stand. It is the quickest way back into a session you left an hour ago — or into whichever of five running sessions you switch to next.",[10,4673,4674],{},"The panel refreshes itself each time the agent stops, provided you have that session open with the panel showing: a session working in the background never spends a turn on a summary nobody is watching, and catches up the moment you come back to it. The refresh button in the panel's header regenerates it on demand. A refresh that finds the transcript unchanged does nothing at all, and an ordinary one sends only the turns since the last summary rather than the whole conversation. The summary is stored with the session, so it survives quitting Plexus and is on screen the instant you reopen the panel.",[105,4676,4678],{"id":4677},"turning-it-on","Turning it on",[10,4680,4681,4682,4685],{},"Summaries are ",[52,4683,4684],{},"off"," until you ask for them, because each one spends a turn. Open the panel on any session and it says exactly that, and offers two ways to switch them on:",[331,4687,4688,4694],{},[334,4689,4690,4693],{},[52,4691,4692],{},"Turn on for \u003Cproject>"," — this project only, and every session in it. That is the narrowest scope the setting has; there is no per-session version.",[334,4695,4696,4699],{},[52,4697,4698],{},"Turn on everywhere"," — the global default, for every project.",[10,4701,4702,4703,4706],{},"Either button writes the ",[52,4704,4705],{},"AI session summary"," setting at that layer and then generates the first summary straight away, instead of leaving you waiting for the agent's next stop. Nothing is read from the session's transcript until you press one: while the feature is off, the panel only describes it.",[47,4708,4709],{},[10,4710,4711],{},"Each refresh sends the session's transcript to the agent and uses one of your plan's turns. That is why summaries are off until you turn them on.",[10,4713,4714,4717,4718,4721],{},[52,4715,4716],{},"Model for session summaries"," decides which model writes it — Haiku by default, so a summary lands quickly. Both settings sit under Settings → Agent and can be set globally or overridden per workspace or project; see ",[99,4719,102],{"href":4720},"\u002Fdocs\u002Fsettings#session-summary",", which is also where you switch summaries back off.",[14,4723,4725],{"id":4724},"archive-vs-remove","Archive vs. remove",[10,4727,4728,4729,4731],{},"Plexus gives you two ways to retire a session, and they are not the same. Reach both from the per-row ",[22,4730,1083],{}," menu.",[190,4733,4734,4747],{},[193,4735,4736],{},[196,4737,4738,4741,4744],{},[199,4739,4740],{},"Action",[199,4742,4743],{},"What it does",[199,4745,4746],{},"Reversible?",[209,4748,4749,4766],{},[196,4750,4751,4757,4763],{},[214,4752,4753,4756],{},[52,4754,4755],{},"Archive"," (soft)",[214,4758,4759,4760,4762],{},"Hides the session in the ",[52,4761,1633],{}," drawer but keeps its worktree, branch, and transcript.",[214,4764,4765],{},"Yes — unarchive to restore it.",[196,4767,4768,4774,4777],{},[214,4769,4770,4773],{},[52,4771,4772],{},"Remove"," (hard)",[214,4775,4776],{},"Runs teardown hooks, removes the worktree and (optionally) its branch, and drops the session row. A branch Plexus didn't create takes an extra confirmation.",[214,4778,4779],{},"No — it's permanent.",[10,4781,4782,4783,4786,4787,4790],{},"Removal is idempotent: if a ",[99,4784,4785],{"href":388},"teardown hook"," fails, or the worktree was already deleted out of band, removal still completes. It also clears git's own record of the worktree, not just the folder — otherwise git would keep treating the session's branch as checked out somewhere and refuse to delete or check it out. A worktree that genuinely can't be removed — something is still holding its files — is reported rather than silently skipped, so it never disappears from view while it's still on disk. If you asked for the branch to go too and git kept it — another worktree still has it checked out — Plexus says so instead of reporting a clean removal, so you can delete it from the project's ",[99,4788,369],{"href":4789},"\u002Fdocs\u002Fproject-git#context-menus",". Root-tree sessions have no separate worktree, so removing them skips worktree removal.",[10,4792,4793,4794,4797,4798,4801,4802,4805],{},"Deleting the branch of a session that ",[52,4795,4796],{},"cut"," its own ",[22,4799,4800],{},"plexus\u002F…"," branch is the ordinary case, and it's forceful: that branch existed only for the session, so it goes even if it still carries commits. A session started on an ",[52,4803,4804],{},"existing"," branch is treated differently, because that branch outlives the session and may be someone else's:",[331,4807,4808,4814,4821,4835],{},[334,4809,4810,4811,4813],{},"The branch checkbox in the removal dialog starts ",[52,4812,4684],{},", and stays off — Plexus never pre-ticks it from what you chose last time.",[334,4815,4816,4817,4820],{},"Ticking it brings a ",[52,4818,4819],{},"second confirmation naming the branch",", so deleting it is always a deliberate, specific act.",[334,4822,4823,4824,4827,4828,4831,4832,4834],{},"The deletion itself is the safe kind (",[22,4825,4826],{},"git branch -d","). A branch still carrying commits that are merged nowhere else is ",[52,4829,4830],{},"kept",", and reported as kept rather than quietly skipped. If you really do want it gone, delete it from the project ",[99,4833,369],{"href":4789},", which offers the forceful version and spells out that its commits go with it.",[334,4836,2199,4837,4841],{},[99,4838,4840],{"href":4839},"\u002Fdocs\u002Fpull-requests#after-the-pr-is-created","automatic cleanup after a merge"," holds the same line without you present: it never deletes a branch that existed before the session, because there is no dialog in which to confirm one.",[10,4843,2199,4844,4846,4847,4849,4850,4852],{},[52,4845,1633],{}," drawer — opened from the button at the bottom of the sidebar — lists archived sessions alongside archived projects, each with ",[52,4848,1637],{}," and permanent-delete actions. You can archive a whole ",[99,4851,1602],{"href":2058}," the same way you archive a session.",[10,4854,4855,4856,4859,4860,4863,4864,4867,4868,4870,4871,4873,4874,4877,4878,4881,4882,4885],{},"Removing a project or a workspace asks the same question the archive dialog does: ",[52,4857,4858],{},"Tear down worktrees"," (and optionally their branches), off by default. Leaving it off keeps every worktree on disk — reclaim them later from the Git tab's ",[99,4861,4862],{"href":4789},"Worktrees section",". These bulk paths can't stop and ask about one branch at a time, so they hold the same line: ",[52,4865,4866],{},"Also delete branches"," covers only the ",[22,4869,4800],{}," branches Plexus cut, and a branch a session merely checked out is ",[52,4872,4830],{},". Taking those too is a third switch, ",[52,4875,4876],{},"Also delete branches Plexus didn't create",", and ticking it asks again — listing exactly which branches it means and which session each belongs to, archived sessions included. Even then the deletion is the safe kind: a branch still carrying unmerged commits is kept, and counted in what the dialog reports as left behind. Either way, the agents running in those sessions are stopped first, and the ",[99,4879,4880],{"href":388},"teardown hooks"," of every session that was ",[52,4883,4884],{},"started"," run: a delete drops the sessions for good, so it's the last chance those hooks get to shut down containers or clean up whatever else they were written for. (Archiving is different — it's restorable, so its keep-the-worktrees path leaves the hooks for the eventual real teardown.)",[47,4887,4888],{"tone":69},[10,4889,4890,4891,4894,4895,4898,4899,502],{},"Teardown hooks are ordinary shell commands, and the plan includes the ones the repository ships in its own ",[22,4892,4893],{},".plexus\u002Fhooks.json"," — so deleting a project runs commands that repository defined. Sessions you never started are skipped: nothing was set up for them to tear down, and deleting a repository is never the first thing to run its hooks. Turn repository hooks off with ",[52,4896,4897],{},"Run scripts committed to the repository"," (Settings → Worktrees & Hooks — see ",[99,4900,389],{"href":4901},"\u002Fdocs\u002Fhooks#repo-committed-hooks",[105,4903,4905],{"id":4904},"teardown-mode","Teardown mode",[10,4907,2199,4908,4911,4912,4915],{},[52,4909,4910],{},"When you remove a session"," setting (Settings → General) controls what ",[52,4913,4914],{},"Remove session…"," actually does:",[190,4917,4918,4928],{},[193,4919,4920],{},[196,4921,4922,4925],{},[199,4923,4924],{},"Option",[199,4926,4927],{},"Behavior",[209,4929,4930,4940,4950],{},[196,4931,4932,4937],{},[214,4933,4934],{},[52,4935,4936],{},"Delete immediately",[214,4938,4939],{},"Hard-delete the worktree right away (the default).",[196,4941,4942,4947],{},[214,4943,4944],{},[52,4945,4946],{},"Archive (keep a restorable copy)",[214,4948,4949],{},"Archive the session instead of deleting it.",[196,4951,4952,4957],{},[214,4953,4954],{},[52,4955,4956],{},"Ask each time",[214,4958,4959],{},"Ask whether to archive or delete each time.",[10,4961,4962,4963,4966,4967,4969],{},"One other thing follows this setting: the ",[99,4964,4965],{"href":4839},"merged-pull-request cleanup",". It runs unattended, so it never stops to ask — ",[52,4968,4956],{}," deletes there.",[47,4971,4972],{"tone":69},[10,4973,4974,4975,4977,4978,4980,4981,4983,4984,4986,4987,4991,4992,853,4994,4996,4997,4999],{},"With ",[52,4976,4910],{}," left at its default of ",[52,4979,4936],{},", removing a session tears down its worktree and can delete its branch too. The branch checkbox in the confirmation starts ",[52,4982,4684],{},"; once you tick it for a ",[22,4985,4800],{}," branch Plexus cut, that answer is remembered for next time — and it is the same answer the automatic merged-pull-request cleanup inherits, unattended, from then on. For a branch that existed before the session the checkbox always starts off and ticking it asks a second time — see ",[99,4988,4990],{"href":4989},"#archive-vs-remove","above",". Switch the setting to ",[52,4993,4755],{},[52,4995,4956],{}," in ",[99,4998,102],{"href":101}," if you want a safer default.",{"title":33,"searchDepth":266,"depth":266,"links":5001},[5002,5009,5012,5015],{"id":4228,"depth":266,"text":4229,"children":5003},[5004,5005,5006,5007,5008],{"id":4252,"depth":271,"text":4253},{"id":4293,"depth":271,"text":1261},{"id":4313,"depth":271,"text":1265},{"id":4439,"depth":271,"text":3281},{"id":4523,"depth":271,"text":1284},{"id":4538,"depth":266,"text":4539,"children":5010},[5011],{"id":4557,"depth":271,"text":4558},{"id":4651,"depth":266,"text":4652,"children":5013},[5014],{"id":4677,"depth":271,"text":4678},{"id":4724,"depth":266,"text":4725,"children":5016},[5017],{"id":4904,"depth":271,"text":4905},"A session is one agent in its own git worktree, on a branch it cuts for you or one that already exists.","Working with sessions","Bot",{},20,{"title":1270,"description":5018},"docs\u002Fsessions","4jBGMdh6VNczNFsRIW-XC4z_y2K-Ry2BFmLZEtIA2bw",{"id":5027,"title":5028,"body":5029,"description":5542,"extension":277,"group":5019,"icon":1688,"meta":5543,"navTitle":349,"navigation":281,"order":5544,"path":348,"seo":5545,"stem":5546,"__hash__":5547},"docs\u002Fdocs\u002Fstatus.md","Status & notifications",{"type":7,"value":5030,"toc":5529},[5031,5034,5038,5041,5058,5066,5072,5084,5092,5095,5098,5141,5147,5170,5183,5204,5208,5239,5250,5260,5286,5295,5299,5302,5337,5340,5349,5352,5358,5364,5368,5380,5384,5393,5406,5411,5415,5422,5428,5436,5448,5452,5460,5463,5489,5495,5510,5515],[10,5032,5033],{},"Every session row carries two indicators — an activity dot, which grows a blue ring when the agent has background work running, and a branch\u002FPR icon — so you can tell at a glance what the agent is doing and where its branch stands.",[14,5035,5037],{"id":5036},"the-activity-dot","The activity dot",[10,5039,5040],{},"A colored dot sits next to each session and tracks what the session's own agent is doing right now:",[331,5042,5043,5048,5053],{},[334,5044,5045,5047],{},[52,5046,1698],{}," — emerald, with a live pulse. The agent is mid-turn: thinking, running tools, editing files.",[334,5049,5050,5052],{},[52,5051,1704],{}," — amber. The turn finished, or the agent is paused on you — a question, a permission prompt, or a plan waiting for your approval. It's your turn.",[334,5054,5055,5057],{},[52,5056,1710],{}," — gray. The session is stopped, or running with nothing in flight.",[10,5059,5060,5061,5065],{},"Every session is in exactly one of those three states, and the dot is about the main agent only. Work it handed to subagents and left running is a separate indicator — see ",[99,5062,5064],{"href":5063},"#background-subagents","Background subagents"," below.",[10,5067,5068,5069,5071],{},"The dot is driven by Claude Code's own lifecycle events, bridged back over a private loopback channel — so it follows what the agent is really doing rather than guessing. When a session starts, Plexus installs a small set of activity hooks into the session's working directory. The dot flips to ",[52,5070,2154],{}," the instant a turn ends, and also when the agent pauses for a plan approval or a multiple-choice question — so a session that needs you never sits there looking busy.",[10,5073,5074,5075,5077,5078,5080,5081,5083],{},"Only the session's own agent moves its dot. Opening another ",[22,5076,24],{}," in the same folder — in the built-in terminal, an outside shell, or one the agent spawns itself — won't repaint a working session's status. And the dot self-heals: if it reads idle while the agent is demonstrably paused on a plan or question, Plexus flips it to ",[52,5079,2154],{}," within a couple of seconds; if it reads idle mid-task, it flips back to ",[52,5082,2150],{}," as soon as the agent's transcript shows fresh activity.",[47,5085,5086],{},[10,5087,5088,5089,5091],{},"The indicator stays accurate across the whole ",[99,5090,1679],{"href":1357},", so you can watch several sessions at once and see exactly which one wants attention without opening each one.",[14,5093,5064],{"id":5094},"background-subagents",[10,5096,5097],{},"When the agent hands work to subagents and carries on without waiting for them, a blue pulsing ring appears around the activity dot. The ring is a second, independent signal, so it combines with all three dot colors:",[190,5099,5100,5110],{},[193,5101,5102],{},[196,5103,5104,5107],{},[199,5105,5106],{},"What you see",[199,5108,5109],{},"What it means",[209,5111,5112,5120,5131],{},[196,5113,5114,5117],{},[214,5115,5116],{},"Emerald dot + blue ring",[214,5118,5119],{},"The agent is mid-turn, and delegated work is running alongside it.",[196,5121,5122,5128],{},[214,5123,5124,5125],{},"Amber dot + blue ring, ",[52,5126,5127],{},"Delegating",[214,5129,5130],{},"It's your turn — you can prompt the agent now — while the delegated work continues.",[196,5132,5133,5138],{},[214,5134,5135,5136],{},"Gray dot + blue ring, ",[52,5137,5127],{},[214,5139,5140],{},"The session itself has nothing in flight, but delegated work is still finishing.",[10,5142,5143,5144,132],{},"Hover the dot for the count: ",[91,5145,5146],{},"\"Agent working — 3 subagents running\"",[10,5148,5149,5150,5153,5154,5156,5157,853,5160,5162,5163,5166,5167,5169],{},"At Normal ",[99,5151,5152],{"href":101},"density",", where a session row names the state in words on its second line, those last two rows say ",[52,5155,5127],{}," in blue rather than ",[91,5158,5159],{},"Needs you",[91,5161,1710],{}," — the main agent isn't mid-turn, and the delegated work is what's still running. The ",[99,5164,5165],{"href":1780},"context bar"," says the same for the session you have open. A session whose agent is mid-turn keeps saying ",[91,5168,1698],{},", ring or no ring.",[10,5171,5172,5173,5176,5177,5179,5180,132],{},"The word is about the main agent being free, not about nothing being asked of you. A turn that hands work off and ",[91,5174,5175],{},"then"," stops on a question, a permission prompt or a plan waiting for approval also reads ",[52,5178,5127],{}," while the ring is lit. The dot is how you tell the two apart: it stays amber, and hovering it says ",[91,5181,5182],{},"\"Waiting for input — 2 subagents running\"",[10,5184,5185,5186,5189,5190,5193,5194,5196,5197,756,5200,5203],{},"You also see it where individual sessions aren't on screen: a ",[52,5187,5188],{},"collapsed project"," row shows how many of its sessions are delegating, the ",[52,5191,5192],{},"workspace switcher"," in the app bar shows the same for the workspace you're in (and its menu shows it per workspace), and a session's second line in ",[52,5195,2274],{}," search says it in words — ",[91,5198,5199],{},"Delegating · 2",[91,5201,5202],{},"Working · 2 delegating"," when the agent is mid-turn alongside them.",[105,5205,5207],{"id":5206},"which-agents-light-the-ring","Which agents light the ring",[331,5209,5210,5220,5233],{},[334,5211,5212,5215,5216,5219],{},[52,5213,5214],{},"Background subagents do"," — work the agent handed off and carried on without waiting for. That includes a batch started by a ",[52,5217,5218],{},"workflow",", which fans work out to several agents running in parallel.",[334,5221,5222,5225,5226,5229,5230,5232],{},[52,5223,5224],{},"Foreground subagents don't."," A subagent the agent is sitting and waiting on isn't something running beside it — it ",[91,5227,5228],{},"is"," the agent working, so the session shows a plain emerald ",[52,5231,2150],{}," dot and no ring.",[334,5234,5235,5238],{},[52,5236,5237],{},"Other background work doesn't."," A shell command the agent left running in the background, and other kinds of background task, aren't subagents.",[47,5240,5241],{},[10,5242,5243,5246,5247],{},[52,5244,5245],{},"\"My subagents didn't show up.\""," Most often nothing was missed: the agent was waiting on them, so they were foreground work and the session was showing you the emerald working dot instead. The ring answers a different question — ",[91,5248,5249],{},"is there work running beside this session?",[10,5251,5252,5253,5256,5257,5259],{},"The ring is worked out from several signals at once. Only a launch can turn it ",[91,5254,5255],{},"on",", and every other signal can only turn it ",[91,5258,4684],{}," — so it can't be left lit over work that has already finished:",[331,5261,5262,5268,5271,5277,5280,5283],{},[334,5263,5264,5265,5267],{},"Claude Code tells Plexus the instant the agent hands work off, so the ring appears as the work starts. This is also what covers the case that used to hide it altogether: a turn that delegates ",[91,5266,3667],{}," stops to ask you a question or show you a plan.",[334,5269,5270],{},"Plexus also reads the session's own conversation record every couple of seconds, as a check that doesn't depend on anything being reported to it.",[334,5272,5273,5274,5276],{},"Work started by a ",[52,5275,5218],{}," is followed through the workflow's own run, which is the only place its individual agents are recorded — so a fan-out lights the ring and each agent drops off it as it finishes.",[334,5278,5279],{},"Claude Code reports the work it still has in flight, both when the agent's turn ends and each time an individual subagent finishes. That report is the authority in both directions — a subagent that has finished drops off the ring immediately.",[334,5281,5282],{},"Each running subagent is watched for progress of its own. One that has gone quiet for 30 minutes is dropped, which covers work whose ending was never recorded anywhere — the CLI was killed, or the conversation was cleared mid-delegation.",[334,5284,5285],{},"Stopping the session, the agent exiting on its own, archiving its project, quitting Plexus, or resetting the session's status (see below) clears the ring straight away.",[47,5287,5288],{},[10,5289,5290,5291,132],{},"The ring is quiet by design: Plexus doesn't alert you while background work is running, only once it drains — see ",[99,5292,5294],{"href":5293},"#getting-notified","Getting notified",[14,5296,5298],{"id":5297},"the-branch-pr-icon","The branch \u002F PR icon",[10,5300,5301],{},"A second icon shows the git state of the session's branch, color-coded by pull request status:",[190,5303,5304,5314],{},[193,5305,5306],{},[196,5307,5308,5311],{},[199,5309,5310],{},"Color",[199,5312,5313],{},"Meaning",[209,5315,5316,5323,5330],{},[196,5317,5318,5320],{},[214,5319,1731],{},[214,5321,5322],{},"Branch only — no open PR (or the PR was closed without merging).",[196,5324,5325,5327],{},[214,5326,1737],{},[214,5328,5329],{},"An open pull request exists for this branch.",[196,5331,5332,5334],{},[214,5333,1743],{},[214,5335,5336],{},"The pull request has been merged.",[10,5338,5339],{},"Hover the icon for details, including the aggregate CI status (pending \u002F passing \u002F failing) for the PR's head commit. When the icon is green or purple, click it to open the pull request in your browser.",[10,5341,5342,5343,5345,5346,5348],{},"Plexus refreshes PR status automatically — when you focus the window, on a periodic poll, and whenever the agent finishes a turn — so the color stays current as a review progresses. See ",[99,5344,2655],{"href":1469}," for creating and managing PRs, and ",[99,5347,173],{"href":172}," to connect GitHub or Bitbucket.",[14,5350,5294],{"id":5351},"getting-notified",[10,5353,5354,5355,5357],{},"When a session moves to ",[52,5356,2154],{},", Plexus can alert you even if its window is minimized or you're focused on another session.",[10,5359,5360,5361,5363],{},"Background subagents don't change that. While delegated work is still running, a session that goes amber stays quiet — the work isn't finished, so this isn't the moment the session is done with. That holds whether the turn simply ended or the agent paused to ask you something, which is why the row says ",[91,5362,5127],{}," and the dot is what tells you which of the two it is. The alert waits for the real finish: the moment the delegated work drains and the session settles on waiting, you're told once.",[105,5365,5367],{"id":5366},"desktop-notifications","Desktop notifications",[10,5369,5370,5371,5373,5374,5376,5377,5379],{},"A native OS notification names the session and what it needs. Controlled by ",[52,5372,5367],{}," (Settings → General), which is ",[52,5375,5255],{}," by default. On Linux, pop-ups use ",[22,5378,183],{}," when available — install it if notifications don't appear.",[105,5381,5383],{"id":5382},"sound","Sound",[10,5385,5386,5387,5373,5390,5392],{},"An optional brief two-note chime plays when a session needs input. It's synthesized in memory — no audio files. Controlled by ",[52,5388,5389],{},"Notification sound",[52,5391,4684],{}," by default; a preview button lets you play the chime and confirm your audio works.",[10,5394,5395,5396,5399,5400,5402,5403,132],{},"Prefer your own sound? Set a ",[52,5397,5398],{},"custom sound"," under global Settings → General. Plexus copies the file you pick into its own data folder, so it stays on your machine and keeps working even if you move or delete the original — and the ",[52,5401,5389],{}," toggle still decides whether it plays. See the ",[99,5404,5405],{"href":101},"Settings reference",[10,5407,5408,5409,132],{},"Both settings are session-scoped, so you can tune which sessions are allowed to interrupt you. Toggle them under Settings → General — see the ",[99,5410,5405],{"href":101},[14,5412,5414],{"id":5413},"resetting-a-stuck-activity-dot","Resetting a stuck activity dot",[10,5416,5417,5418,5421],{},"Because the dot follows Claude Code's hooks, it can occasionally stick on the wrong state. The usual cause is pressing ",[22,5419,5420],{},"Esc"," to interrupt a turn — Claude Code fires no hook for that, so the dot keeps its previous value.",[10,5423,5424,5425,5427],{},"To clear it, open the session's ",[52,5426,1083],{}," menu and choose to reset its status. The dot flips to idle (gray) immediately, and the subagent ring — which can stick the same way, if a subagent's ending was never recorded — clears with it. This only changes the visual indicators — it doesn't touch Claude's actual session or conversation, and it doesn't stop any subagent that is genuinely still running.",[10,5429,5430,5431,853,5433,5435],{},"A reset on a genuinely stuck dot sticks. If you reset a session whose agent is actually still busy, the self-healing described above kicks in: the dot returns to ",[52,5432,2150],{},[52,5434,2154],{}," once the agent's activity proves the reset was premature — so a mistaken reset can't hide a live agent.",[47,5437,5438],{"tone":69},[10,5439,5440,5441,5444,5445,5447],{},"If the dot stops updating entirely rather than sticking on one value, resetting won't help — something in the chain is disconnected rather than stale. Use ",[52,5442,5443],{},"Check activity hooks…"," in the same ",[52,5446,1083],{}," menu instead; see below.",[14,5449,5451],{"id":5450},"if-the-activity-dot-doesnt-move","If the activity dot doesn't move",[10,5453,5454,5455,4529,5457,5459],{},"A dot that stays gray no matter what the agent does is a different problem from one stuck on the wrong colour: something in the chain between Claude Code and Plexus isn't connected. Open the session's ",[52,5456,1083],{},[52,5458,5443],{}," — it runs a one-click diagnosis and tells you, in a sentence, which link is broken.",[10,5461,5462],{},"It checks four things:",[331,5464,5465,5471,5477,5483],{},[334,5466,5467,5470],{},[52,5468,5469],{},"What's installed."," The hooks Plexus wrote into this session's working directory, and what address they report to.",[334,5472,5473,5476],{},[52,5474,5475],{},"Whether that address is still current."," Plexus picks a fresh address every time it starts, so a session left running from an earlier launch reports to somewhere that no longer exists. The fix is restarting the session, and the check says so.",[334,5478,5479,5482],{},[52,5480,5481],{},"Whether Plexus is reachable."," It sends itself a test message. No answer means something on your machine is blocking local connections — a firewall, security software, or a VPN that captures loopback traffic.",[334,5484,5485,5488],{},[52,5486,5487],{},"Whether Claude Code actually ran the hooks."," Claude Code records what it ran at the end of every turn, so this is answered from the conversation you already had — you don't have to reproduce anything.",[10,5490,5491,5494],{},[52,5492,5493],{},"Copy report"," puts the whole thing on your clipboard, ready to paste into a bug report. It carries no secrets of Plexus's: connection tokens appear only as short fingerprints, and hooks you added yourself are counted but never quoted.",[10,5496,5497,5498,5501,5502,5505,5506,5509],{},"The one exception is the ",[52,5499,5500],{},"hook errors"," the check shows when the last turn had any. Claude Code reports those for the whole turn rather than per hook, so if one of your own hooks failed, its command line and its output appear alongside Plexus's — and that is where an API key or a password of yours can end up. Plexus blanks out the shapes it recognises, but it can't recognise everything a hook might print, so the errors stay on screen and are left ",[52,5503,5504],{},"out"," of the copied report unless you turn on ",[52,5507,5508],{},"Include these in Copy report"," underneath them. The report still says how many there were, so nobody reads it as \"no errors\".",[47,5511,5512],{"tone":69},[10,5513,5514],{},"Read the hook errors before you include them in a report you're posting publicly — they can contain anything your own hooks wrote.",[47,5516,5517],{},[10,5518,5519,5520,5523,5524,5526,5527,132],{},"Still stuck? Turn on ",[52,5521,5522],{},"Diagnostic logging"," under Settings → Advanced, reproduce the problem, then use ",[99,5525,1847],{"href":1846}," — it attaches that trace for you, after showing you exactly what it says. The log keeps the last 7 days. See the ",[99,5528,5405],{"href":101},{"title":33,"searchDepth":266,"depth":266,"links":5530},[5531,5532,5535,5536,5540,5541],{"id":5036,"depth":266,"text":5037},{"id":5094,"depth":266,"text":5064,"children":5533},[5534],{"id":5206,"depth":271,"text":5207},{"id":5297,"depth":266,"text":5298},{"id":5351,"depth":266,"text":5294,"children":5537},[5538,5539],{"id":5366,"depth":271,"text":5367},{"id":5382,"depth":271,"text":5383},{"id":5413,"depth":266,"text":5414},{"id":5450,"depth":266,"text":5451},"Activity dots, PR colors, and alerts when a session needs you.",{},21,{"title":5028,"description":5542},"docs\u002Fstatus","vjV8_FcifBkGjoVrHy8gJ9PW9BBExpB4LX_zMf-2Vy4",{"id":5549,"title":5550,"body":5551,"description":5758,"extension":277,"group":5019,"icon":5759,"meta":5760,"navTitle":1303,"navigation":281,"order":5761,"path":1430,"seo":5762,"stem":5763,"__hash__":5764},"docs\u002Fdocs\u002Fagent.md","The Agent tab",{"type":7,"value":5552,"toc":5750},[5553,5556,5562,5566,5569,5572,5604,5611,5615,5622,5625,5628,5679,5683,5697,5701,5707,5711,5722,5730,5732],[10,5554,5555],{},"The Agent tab is the wrapped Claude Code terminal at the heart of every session — type prompts, watch the agent work, and drive its interactive UI in real time.",[10,5557,5558,5559,5561],{},"It's the default view when you open a session (",[22,5560,1977],{},"). It runs the Claude Code CLI inside the session's worktree and streams its output live, exactly as the agent produces it. Switch away and come back — the terminal stays warm and rehydrates with its full scrollback intact.",[14,5563,5565],{"id":5564},"sending-prompts","Sending prompts",[10,5567,5568],{},"Click the terminal to focus it, then type as you would in any terminal. Claude Code's own slash commands and interactive prompts work as normal.",[1365,5570],{":rows":5571},"[[\"Enter\",\"Submit the current prompt to Claude Code\"],[\"⇧Enter\",\"Insert a newline instead of submitting — for multi-line prompts\"],[\"⌘C\",\"Copy the selected text to the clipboard\"],[\"⌘V\",\"Paste the clipboard (text or an image) into the prompt\"],[\"⌃C\",\"Interrupt the agent (Ctrl+C when no text is selected)\"]]",[47,5573,5574],{},[10,5575,5576,5578,5579,5582,5583,5586,5587,5589,5590,2639,5593,5596,5597,5599,5600,5603],{},[22,5577,1996],{}," means Cmd on macOS and Ctrl on Windows and Linux. ",[22,5580,5581],{},"⌘C"," copies the selection and ",[22,5584,5585],{},"⌘V"," pastes. On Windows and Linux those are the ",[52,5588,4629],{}," ",[22,5591,5592],{},"Ctrl+C",[22,5594,5595],{},"Ctrl+V",": ",[22,5598,5592],{}," copies only when text is selected and otherwise interrupts the agent, so ",[22,5601,5602],{},"⌃C"," still interrupts whenever nothing is selected.",[10,5605,5606,5607,5610],{},"Pasting when the clipboard holds an ",[52,5608,5609],{},"image"," — a screenshot, or an image copied from another app — drops it straight into the prompt as an attachment, so you can ask Claude Code about it without saving a file first.",[14,5612,5614],{"id":5613},"rich-input","Rich input",[10,5616,5617,5618,5621],{},"For longer prompts, open the rich input — a dedicated multi-line compose box at the bottom of the tab. Toggle it with ",[22,5619,5620],{},"⌘I",". While it's focused it keeps the keyboard, so the terminal won't steal your keystrokes; focus returns to the terminal after you submit or close the box.",[10,5623,5624],{},"Need more room? Drag the divider between the terminal and the compose box to resize it — the terminal reflows to fit, and the height you pick is remembered across sessions and restarts.",[10,5626,5627],{},"Two settings tune it:",[190,5629,5630,5641],{},[193,5631,5632],{},[196,5633,5634,5637,5639],{},[199,5635,5636],{},"Setting",[199,5638,1067],{},[199,5640,4743],{},[209,5642,5643,5656],{},[196,5644,5645,5650,5653],{},[214,5646,5647],{},[52,5648,5649],{},"Open the rich input box automatically",[214,5651,5652],{},"Off",[214,5654,5655],{},"Show the compose box automatically instead of starting collapsed",[196,5657,5658,5663,5665],{},[214,5659,5660],{},[52,5661,5662],{},"Send with Ctrl+Enter \u002F Cmd+Enter",[214,5664,5652],{},[214,5666,5667,5668,5671,5672,5675,5676,5678],{},"When off, ",[22,5669,5670],{},"⌘Enter"," pastes the composed text into the terminal so you can review before pressing ",[22,5673,5674],{},"Enter","; when on, ",[22,5677,5670],{}," sends it immediately",[14,5680,5682],{"id":5681},"rewind","Rewind",[10,5684,5685,5686,5689,5690,5692,5693,5696],{},"When ",[52,5687,5688],{},"Show the Rewind button"," (Settings → Agent) is on (the default), a ",[52,5691,5682],{}," control appears on the tab. It opens Claude Code's ",[22,5694,5695],{},"\u002Frewind"," checkpoint picker, letting you roll the conversation — and the file edits made since a checkpoint — back to an earlier point. Turn the setting off to hide the button.",[14,5698,5700],{"id":5699},"dragging-files-in","Dragging files in",[10,5702,5703,5704,5706],{},"Drag a file or folder from your OS file manager and drop it anywhere on the terminal. Plexus inserts the item's absolute path at the cursor, quoted only when the path needs it. No newline is added, so you can drag a file in mid-sentence to reference it before pressing ",[22,5705,5674],{},". A highlight ring marks the terminal under the cursor while you drag.",[14,5708,5710],{"id":5709},"permissions","Permissions",[10,5712,5713,5714,5717,5718,5721],{},"By default ",[52,5715,5716],{},"Let the agent work without asking permission"," (Settings → Agent) is on, which launches Claude Code with ",[22,5719,5720],{},"--dangerously-skip-permissions",". The agent then runs autonomously — ideal for parallel, hands-off sessions.",[47,5723,5724],{"tone":69},[10,5725,5726,5727,5729],{},"Turn ",[52,5728,5716],{}," off (globally, or per workspace or project) if you'd rather have the agent stop and ask before sensitive actions. Because it decides how the agent launches, it's resolved at session start.",[14,5731,2343],{"id":2342},[331,5733,5734,5740,5745],{},[334,5735,5736,5739],{},[99,5737,5738],{"href":1969},"The terminal"," — the bottom panel's plain scratch shells, separate from the wrapped agent",[334,5741,5742,5744],{},[99,5743,2000],{"href":1476}," — the full, customizable shortcut list",[334,5746,5747,5749],{},[99,5748,102],{"href":101}," — every Agent-tab setting and its default",{"title":33,"searchDepth":266,"depth":266,"links":5751},[5752,5753,5754,5755,5756,5757],{"id":5564,"depth":266,"text":5565},{"id":5613,"depth":266,"text":5614},{"id":5681,"depth":266,"text":5682},{"id":5699,"depth":266,"text":5700},{"id":5709,"depth":266,"text":5710},{"id":2342,"depth":266,"text":2343},"Talk to Claude Code in the wrapped agent terminal.","Sparkles",{},22,{"title":5550,"description":5758},"docs\u002Fagent","Y_GLreFiOwj3pHJUvjuib74s_hBq-1UgJHi26EEznuw",{"id":5766,"title":5767,"body":5768,"description":6091,"extension":277,"group":5019,"icon":6092,"meta":6093,"navTitle":379,"navigation":281,"order":6094,"path":378,"seo":6095,"stem":6096,"__hash__":6097},"docs\u002Fdocs\u002Fexplorer.md","Explorer & editor",{"type":7,"value":5769,"toc":6079},[5770,5778,5781,5787,5791,5798,5821,5831,5835,5842,5845,5851,5855,5884,5888,5891,5894,5901,5947,5953,5957,5973,6016,6019,6023,6059,6062,6066,6069],[10,5771,5772,5773,4007,5775,5777],{},"The Explorer tab is a file browser and code editor scoped to the session's git worktree. Switch to it with ",[22,5774,4088],{},[22,5776,1996],{}," is Cmd on macOS, Ctrl on Windows and Linux.",[10,5779,5780],{},"The tab splits into two resizable panes: a file tree on the left and a Monaco editor on the right.",[10,5782,5783],{},[1096,5784],{"alt":5785,"src":5786},"The Explorer tab: the worktree file tree on the left, the Monaco editor with an open file on the right.","\u002Fdocs\u002Fexplorer.png",[14,5788,5790],{"id":5789},"browse-the-file-tree","Browse the file tree",[10,5792,5793,5794,5797],{},"The left pane lists everything in the session's worktree. Folders appear first, then files in case-insensitive alphabetical order, and the ",[22,5795,5796],{},".git"," folder is hidden.",[331,5799,5800,5803,5806,5818],{},[334,5801,5802],{},"Click a folder row to expand it. Contents load lazily on first expand — you'll see a brief spinner — then stay cached so re-expanding is instant.",[334,5804,5805],{},"The cache refreshes quietly in the background after agent turns and git operations, so the tree keeps up with the changes the agent makes without a manual refresh.",[334,5807,5808,5809,5812,5813,5817],{},"Click a file to open it in the editor. Each file you open gets its own ",[52,5810,5811],{},"tab"," above the editor, so several files stay open at once (see ",[99,5814,5816],{"href":5815},"#tabs","Tabs"," below).",[334,5819,5820],{},"Files changed versus the branch this worktree was created from are flagged in the tree: a colored dot on the file (green added, amber modified, red deleted) and a subtle dot on any folder that contains changes — so the files the agent touched are easy to find.",[10,5822,5823,5824,5826,5827,5830],{},"The tree is read-only: there are no New File or Delete actions. New files come from saving to a path in the editor (the parent folder must already exist); deletion is done from a ",[99,5825,1970],{"href":1969}," or your usual tools. If no session is started yet, the tree shows ",[52,5828,5829],{},"No worktree yet"," — start the session to populate it.",[14,5832,5834],{"id":5833},"edit-and-save-files","Edit and save files",[10,5836,5837,5838,5817],{},"Open a file and type to edit it. Syntax highlighting is automatic, detected from the filename and extension — the editor covers around 90 languages (see ",[99,5839,5841],{"href":5840},"#supported-languages","Supported languages",[105,5843,5816],{"id":5844},"tabs",[10,5846,5847,5848,5850],{},"Every file you open gets a tab above the editor. Open as many as you like — clicking a file that's already open just switches to its tab, and switching between tabs preserves each file's unsaved edits, scroll position, and cursor. A tab with unsaved changes shows an amber dot; hover it and click the ",[52,5849,2746],{}," (or middle-click the tab) to close it. Closing a tab with unsaved changes asks you to confirm first. Your open tabs are remembered per session, so switching to another tab (Review, Git) and back — or reopening the app — brings them back.",[105,5852,5854],{"id":5853},"saving","Saving",[10,5856,5857,5858,5861,5862,5865,5866,4996,5869,630,5871,5874,5875,5878,5879,5881,5882,132],{},"By default Plexus saves ",[52,5859,5860],{},"manually",": press ",[22,5863,5864],{},"⌘S"," to write the active file to the worktree. There is no separate Save button — the tab's amber dot is your unsaved-changes indicator. Prefer to save as you go? Turn on ",[52,5867,5868],{},"auto-save",[99,5870,102],{"href":101},[52,5872,5873],{},"Editor → Save behavior → Auto",") and Plexus writes each change to disk a moment after you stop typing, like PhpStorm — the dot clears on its own. You can rebind the save shortcut under ",[52,5876,5877],{},"Settings → Keybindings"," (see ",[99,5880,2000],{"href":1476},"). If a read or save fails, a red error bar explains why. The editor's colors follow the app's light\u002Fdark theme and update the moment you change it in ",[99,5883,1911],{"href":1910},[105,5885,5887],{"id":5886},"change-markers","Change markers",[10,5889,5890],{},"Down the editor's gutter and scrollbar, colored markers show where the file differs from the branch the worktree was created from — green for added lines, amber for modified, and a red caret where lines were removed. The editor always shows the real current file; the markers just point at what changed, so you can review the agent's edits in context. They refresh when you save and automatically after the agent finishes a turn — and in auto-save mode they track your edits almost live.",[14,5892,5841],{"id":5893},"supported-languages",[10,5895,5896,5897,5900],{},"Highlighting comes from the Monaco engine the editor is built on, which bundles around 90 languages. Plexus picks the right one automatically from the filename and extension — files like ",[22,5898,5899],{},"Dockerfile"," are matched by name, no extension needed — so you never set a language by hand.",[190,5902,5903,5913],{},[193,5904,5905],{},[196,5906,5907,5910],{},[199,5908,5909],{},"Category",[199,5911,5912],{},"Languages",[209,5914,5915,5923,5931,5939],{},[196,5916,5917,5920],{},[214,5918,5919],{},"Web & markup",[214,5921,5922],{},"HTML, CSS, SCSS, Less, JavaScript, TypeScript, Vue, JSON, GraphQL, XML, Markdown, Pug, Handlebars",[196,5924,5925,5928],{},[214,5926,5927],{},"Systems & compiled",[214,5929,5930],{},"C, C++, C#, Rust, Go, Swift, Objective-C, WGSL",[196,5932,5933,5936],{},[214,5934,5935],{},"JVM & scripting",[214,5937,5938],{},"Java, Kotlin, Scala, Python, Ruby, PHP, Perl, Lua, R, Dart, Elixir, Clojure, F#, Julia",[196,5940,5941,5944],{},[214,5942,5943],{},"Shell, data & config",[214,5945,5946],{},"Shell \u002F Bash, PowerShell, Batch, Dockerfile, YAML, TOML, INI, HCL, Protobuf, SQL (MySQL, PostgreSQL, Redshift)",[10,5948,5949,5950,5952],{},"The table covers the common ones; the full set is whatever Monaco ships. A file Monaco doesn't recognize opens as plain text — still fully editable, just without coloring. The ",[99,5951,359],{"href":358}," tab highlights a focused subset of these in its diffs.",[14,5954,5956],{"id":5955},"preview-markdown","Preview Markdown",[10,5958,5959,5960,1432,5963,1432,5966,1432,5969,5972],{},"Open a Markdown file (",[22,5961,5962],{},".md",[22,5964,5965],{},".markdown",[22,5967,5968],{},".mdown",[22,5970,5971],{},".mkd",") and three view buttons appear above the editor:",[190,5974,5975,5984],{},[193,5976,5977],{},[196,5978,5979,5982],{},[199,5980,5981],{},"View",[199,5983,2094],{},[209,5985,5986,5996,6006],{},[196,5987,5988,5993],{},[214,5989,5990],{},[52,5991,5992],{},"Source",[214,5994,5995],{},"The raw Markdown",[196,5997,5998,6003],{},[214,5999,6000],{},[52,6001,6002],{},"Preview",[214,6004,6005],{},"The rendered HTML",[196,6007,6008,6013],{},[214,6009,6010],{},[52,6011,6012],{},"Split",[214,6014,6015],{},"Source on the left, live preview on the right",[10,6017,6018],{},"In Split view the preview reflects your unsaved edits as you type, so you see the rendered result before saving. Relative links and images resolve against the worktree, and external links open in your browser. The view resets to Source when you switch to a different file.",[14,6020,6022],{"id":6021},"limits-and-unsupported-files","Limits and unsupported files",[190,6024,6025,6034],{},[193,6026,6027],{},[196,6028,6029,6032],{},[199,6030,6031],{},"Situation",[199,6033,5106],{},[209,6035,6036,6048],{},[196,6037,6038,6041],{},[214,6039,6040],{},"File larger than 1 MB",[214,6042,6043,6044,6047],{},"A ",[52,6045,6046],{},"File too large"," notice with the byte size, instead of the editor",[196,6049,6050,6053],{},[214,6051,6052],{},"Binary file (contains null bytes)",[214,6054,6043,6055,6058],{},[52,6056,6057],{},"Binary file"," notice — it can't be shown or edited",[10,6060,6061],{},"These limits keep the editor responsive and apply to the Markdown preview as well.",[14,6063,6065],{"id":6064},"layout","Layout",[10,6067,6068],{},"Drag the divider between the tree and the editor to resize the panes, and the divider between editor and preview in Split view. Pane sizes are remembered between visits.",[47,6070,6071],{},[10,6072,6073,6074,6076,6077,132],{},"The Explorer is for browsing and quick edits. To direct the agent doing the work, use the ",[99,6075,1431],{"href":1430},"; to review and stage the resulting changes, use the ",[99,6078,369],{"href":368},{"title":33,"searchDepth":266,"depth":266,"links":6080},[6081,6082,6087,6088,6089,6090],{"id":5789,"depth":266,"text":5790},{"id":5833,"depth":266,"text":5834,"children":6083},[6084,6085,6086],{"id":5844,"depth":271,"text":5816},{"id":5853,"depth":271,"text":5854},{"id":5886,"depth":271,"text":5887},{"id":5893,"depth":266,"text":5841},{"id":5955,"depth":266,"text":5956},{"id":6021,"depth":266,"text":6022},{"id":6064,"depth":266,"text":6065},"Browse the worktree and edit files in the built-in editor.","FileText",{},23,{"title":5767,"description":6091},"docs\u002Fexplorer","YzRGR-A-i1qjz7PMm7ylbDbHhUcG2vJFc4SpIUrT7_U",{"id":6099,"title":6100,"body":6101,"description":7317,"extension":277,"group":5019,"icon":7318,"meta":7319,"navTitle":359,"navigation":281,"order":7320,"path":358,"seo":7321,"stem":7322,"__hash__":7323},"docs\u002Fdocs\u002Freview.md","Review & diffs",{"type":7,"value":6102,"toc":7290},[6103,6106,6110,6129,6132,6138,6142,6186,6189,6193,6202,6205,6223,6230,6233,6242,6247,6251,6277,6283,6297,6299,6302,6522,6528,6532,6572,6575,6588,6594,6606,6610,6622,6632,6635,6641,6651,6655,6741,6745,6773,6777,6791,6797,6801,6811,6839,6846,6856,6865,6871,6892,6904,6912,6917,6920,6936,6941,6947,6960,6970,6975,6979,6988,6992,7049,7052,7058,7062,7072,7077,7086,7106,7110,7123,7183,7197,7212,7216,7219,7239,7249,7253,7256,7265,7267],[10,6104,6105],{},"The Review tab is a PR-style diff of a session's worktree against its base branch, where you leave inline comments the agent acts on.",[14,6107,6109],{"id":6108},"the-diff-view","The diff view",[10,6111,6112,6113,6116,6117,6120,6121,6124,6125,6128],{},"The header shows the base ref and totals — ",[22,6114,6115],{},"15 changed files vs. origin\u002Fmain"," with a green ",[22,6118,6119],{},"+234"," \u002F red ",[22,6122,6123],{},"-56"," count across the whole diff. When the base branch has an upstream, Plexus compares against the remote-tracking ref (",[22,6126,6127],{},"origin\u002F\u003Cbase>",") so the view mirrors a pull request; a purely-local base compares against the local ref.",[10,6130,6131],{},"The tab is a resizable two-pane layout: a file list on the left, the selected file's diff on the right. Drag the divider to set your width — it's remembered between sessions.",[10,6133,6134],{},[1096,6135],{"alt":6136,"src":6137},"The Review tab: the list of changed files on the left, a unified diff of the selected file on the right.","\u002Fdocs\u002Freview.png",[105,6139,6141],{"id":6140},"file-list","File list",[10,6143,6144,6145,6148,6149,6152,6153,6156,6157,6160,6161,6164,6165,2801,6167,6170,6171,6174,6175,6177,6178,6181,6182,6185],{},"Each row shows the change type (",[22,6146,6147],{},"A"," added, ",[22,6150,6151],{},"M"," modified, ",[22,6154,6155],{},"D"," deleted, ",[22,6158,6159],{},"R"," renamed, ",[22,6162,6163],{},"C"," copied), the path, its ",[22,6166,1903],{},[22,6168,6169],{},"-"," line counts, and two comment badges: a speech bubble counting the file's open comments, and a check counting its resolved ones. Each appears only when it has something to count, so a file whose comments have all been resolved still says so on the list instead of reading like a file nobody ever opened, and a file with no comments at all shows neither. Your own notes count one apiece; a ",[99,6172,1470],{"href":6173},"#pull-request-comments"," thread counts once however many replies it carries. Untracked files appear marked ",[22,6176,6147],{}," so you can review new files alongside tracked ones. Toggle the sidebar header between a flat ",[52,6179,6180],{},"list"," (with dimmed directory paths) and a directory ",[52,6183,6184],{},"tree"," — switching is instant and keeps your selection.",[10,6187,6188],{},"Click a file to load its diff.",[105,6190,6192],{"id":6191},"hunks","Hunks",[10,6194,6195,6196,6199,6200,132],{},"Each file renders as diff hunks — a ",[22,6197,6198],{},"@@"," header, line numbers, and context, added (green), and deleted (red) lines. Lines are syntax-highlighted and upgrade from plain text to colored tokens once the grammar loads, so the view never blocks — see ",[99,6201,5841],{"href":5840},[10,6203,6204],{},"The bar above the diff switches between two layouts. It stays pinned to the top of the pane as you scroll, so you can switch from anywhere in a long file:",[331,6206,6207,6218],{},[334,6208,6209,6212,6213,2801,6215,6217],{},[52,6210,6211],{},"Unified"," — a single column with the old and new lines interleaved, each row carrying a ",[22,6214,1903],{},[22,6216,6169],{}," marker and both line numbers.",[334,6219,6220,6222],{},[52,6221,6012],{}," — the old file on the left, the new file on the right, with each deleted line opposite the line that replaced it. Where one side has no counterpart — a pure addition or deletion — the other column shows a blank cell.",[10,6224,6225,6226,6229],{},"In both layouts, when a deleted line is paired with its replacement Plexus marks the ",[52,6227,6228],{},"words that actually changed"," inside the line, so a one-character edit doesn't read as a whole-line rewrite. On a hunk that rewrites hundreds of lines at once the word marks are skipped — the red\u002Fgreen line tint already tells that story, and skipping keeps the diff quick to open.",[10,6231,6232],{},"Inline comments work the same either way. In split view the comment button appears on the side a comment anchors to — the left column for a deleted line, the right column for added and unchanged lines — so you can comment on either version of a modified line.",[10,6234,6235,6236,2703,6239,132],{},"Your choice is remembered and applies to every diff in the app, including the read-only diffs in the ",[99,6237,6238],{"href":368},"session Git tab",[99,6240,6241],{"href":373},"project Git client",[47,6243,6244],{},[10,6245,6246],{},"Binary files and files over the size limits (512 KB or 5000 changed lines) show a placeholder instead of a preview. They still appear in the list with their stats.",[14,6248,6250],{"id":6249},"reviewing-someone-elses-branch","Reviewing someone else's branch",[10,6252,6253,6254,6257,6258,6260,6261,781,6265,6269,6270,6272,6273,6276],{},"You don't have to have written the code to use this tab. Create a session on an ",[99,6255,6256],{"href":1269},"existing branch"," — a colleague's branch, or the head of a pull request you've been asked to look at — set ",[52,6259,4336],{}," to the branch it's meant to merge into, and the Review tab becomes a full read of their work: the file list, the diff, your own ",[99,6262,6264],{"href":6263},"#inline-comments","inline comments",[99,6266,6268],{"href":6267},"#ai-review","AI review",", and, once that branch has a ",[99,6271,1470],{"href":1469},", its ",[99,6274,6275],{"href":6173},"review conversation",", where you can reply and resolve without leaving Plexus.",[10,6278,6279,6280,6282],{},"Because the session gets its own worktree, reading someone's branch costs you nothing: your main checkout and your other sessions stay exactly where they were. And if reading turns into fixing, the agent is already sitting in the ",[99,6281,1303],{"href":1430}," tab with that branch checked out.",[47,6284,6285],{"tone":69},[10,6286,6287,6288,6291,6292,6294,6295,132],{},"Committing on a branch someone else also has is ordinary work. ",[52,6289,6290],{},"Rebasing or squashing"," it is not — that rewrites history they may already have pulled. Plexus warns rather than stopping you, and its ",[52,6293,2576],{}," is never a force-push, so a rewrite stays on your machine until you deal with it deliberately. See ",[99,6296,4432],{"href":4362},[14,6298,5841],{"id":5893},[10,6300,6301],{},"The diff view highlights the file types below. Anything else — including a grammar that hasn't finished loading yet — stays readable as plain text.",[190,6303,6304,6314],{},[193,6305,6306],{},[196,6307,6308,6311],{},[199,6309,6310],{},"Language",[199,6312,6313],{},"File types",[209,6315,6316,6328,6338,6348,6358,6368,6378,6391,6404,6413,6423,6433,6443,6456,6466,6476,6489,6499,6509],{},[196,6317,6318,6320],{},[214,6319,6163],{},[214,6321,6322,1432,6325],{},[22,6323,6324],{},".c",[22,6326,6327],{},".h",[196,6329,6330,6333],{},[214,6331,6332],{},"C++",[214,6334,6335],{},[22,6336,6337],{},".cpp",[196,6339,6340,6343],{},[214,6341,6342],{},"CSS",[214,6344,6345],{},[22,6346,6347],{},".css",[196,6349,6350,6353],{},[214,6351,6352],{},"Go",[214,6354,6355],{},[22,6356,6357],{},".go",[196,6359,6360,6363],{},[214,6361,6362],{},"HTML",[214,6364,6365],{},[22,6366,6367],{},".html",[196,6369,6370,6373],{},[214,6371,6372],{},"Java",[214,6374,6375],{},[22,6376,6377],{},".java",[196,6379,6380,6383],{},[214,6381,6382],{},"JavaScript",[214,6384,6385,1432,6388],{},[22,6386,6387],{},".js",[22,6389,6390],{},".jsx",[196,6392,6393,6396],{},[214,6394,6395],{},"JSON",[214,6397,6398,1432,6401],{},[22,6399,6400],{},".json",[22,6402,6403],{},".jsonc",[196,6405,6406,6409],{},[214,6407,6408],{},"Markdown",[214,6410,6411],{},[22,6412,5962],{},[196,6414,6415,6418],{},[214,6416,6417],{},"Python",[214,6419,6420],{},[22,6421,6422],{},".py",[196,6424,6425,6428],{},[214,6426,6427],{},"Rust",[214,6429,6430],{},[22,6431,6432],{},".rs",[196,6434,6435,6438],{},[214,6436,6437],{},"SCSS",[214,6439,6440],{},[22,6441,6442],{},".scss",[196,6444,6445,6448],{},[214,6446,6447],{},"Shell",[214,6449,6450,1432,6453],{},[22,6451,6452],{},".sh",[22,6454,6455],{},".bash",[196,6457,6458,6461],{},[214,6459,6460],{},"SQL",[214,6462,6463],{},[22,6464,6465],{},".sql",[196,6467,6468,6471],{},[214,6469,6470],{},"TOML",[214,6472,6473],{},[22,6474,6475],{},".toml",[196,6477,6478,6481],{},[214,6479,6480],{},"TypeScript",[214,6482,6483,1432,6486],{},[22,6484,6485],{},".ts",[22,6487,6488],{},".tsx",[196,6490,6491,6494],{},[214,6492,6493],{},"Vue",[214,6495,6496],{},[22,6497,6498],{},".vue",[196,6500,6501,6504],{},[214,6502,6503],{},"XML",[214,6505,6506],{},[22,6507,6508],{},".xml",[196,6510,6511,6514],{},[214,6512,6513],{},"YAML",[214,6515,6516,1432,6519],{},[22,6517,6518],{},".yaml",[22,6520,6521],{},".yml",[10,6523,6524,6525,6527],{},"The editor in the ",[99,6526,379],{"href":378}," tab recognizes many more languages; the diff view focuses on this set.",[14,6529,6531],{"id":6530},"inline-comments","Inline comments",[10,6533,6534,6535,6538,6539,1432,6542,1439,6545,6547,6548,6551,6552,6555,6556,6559,6560,6563,6564,6566,6567,6571],{},"Hover a diff line and click the comment button to open the composer, type your note, and click ",[52,6536,6537],{},"Add",". Comments anchor to a specific line on the old or new side (GitHub convention) and appear in a thread below it. Each carries ",[52,6540,6541],{},"Edit",[52,6543,6544],{},"Resolve",[52,6546,3583],{}," actions — plus ",[52,6549,6550],{},"Publish to the pull request"," once the session's ",[99,6553,6554],{"href":6173},"PR conversation"," has loaded — and is labelled ",[52,6557,6558],{},"User"," when you wrote it or ",[52,6561,6562],{},"Plexus Review Agent"," when the ",[99,6565,6268],{"href":6267}," inserted it. Resolving strikes the comment through and moves it from the file's open badge to its resolved one, so the ",[99,6568,6570],{"href":6569},"#file-list","file list"," keeps a record that the file was worked over.",[10,6573,6574],{},"Notes keep their layout: paragraphs, nested lists, indented code blocks and the alignment inside them survive into the Review tab and onto a pull request. Two things are bounded on the way in — a run of spaces is kept up to 16 columns, and a run of blank lines up to two. (The prompt the agent gets still folds each note onto one line.) A very long note is scrollable in its thread rather than pushing the diff off screen.",[10,6576,6577,6578,6582,6583,1751,6585,132],{},"These are private notes until you decide otherwise: they stay on your machine and exist so the agent can read them, and nothing leaves your machine unless you ",[99,6579,6581],{"href":6580},"#publish-a-note-to-the-pull-request","publish one to the pull request"," — which hands that note to GitHub or Bitbucket and consumes your local copy. The comments other people leave on a pull request are a separate conversation with its own authors and its own ",[52,6584,6544],{},[99,6586,6587],{"href":6173},"Pull request comments",[10,6589,6590],{},[1096,6591],{"alt":6592,"src":6593},"The inline comment composer open on a diff line, with a note typed and the Cancel and Add buttons below.","\u002Fdocs\u002Freview-comment.png",[10,6595,6596,6597,6600,6601,1055,6603,6605],{},"Comments are advisory context: if the agent edits a file, line numbers can drift, but your comments stay editable. If an edit removes a file from the diff entirely, its comments become orphaned — a banner at the top lists them by ",[22,6598,6599],{},"file:line"," with ",[52,6602,6544],{},[52,6604,3583],{}," buttons so you can tidy up.",[14,6607,6609],{"id":6608},"send-comments-to-the-agent","Send comments to the agent",[10,6611,6612,6613,6616,6617,6619,6620,502],{},"With unresolved comments open, the header shows a ",[52,6614,6615],{},"Send N comments to agent"," button. Clicking it formats every open comment into one prompt and writes it to the running agent, where Claude reads it as input on its next turn and iterates. The send resolves what it sent, so those comments stop counting toward the button and move to each file's resolved badge — handing your whole review over leaves the ",[99,6618,6570],{"href":6569}," reading as a count of resolved comments per file, rather than emptying it. The session must be running with a live agent — if it's stopped, start it first (see ",[99,6621,1303],{"href":1430},[10,6623,6624,6625,6627,6628,132],{},"That button sends ",[91,6626,1842],{}," notes. Comments from the pull request are sent separately, from their own buttons — see ",[99,6629,6631],{"href":6630},"#send-pr-comments-to-the-agent","Send PR comments to the agent",[14,6633,6587],{"id":6634},"pull-request-comments",[10,6636,6637,6638,6640],{},"Once a session has a ",[99,6639,1470],{"href":1469},", the review conversation moves to GitHub or Bitbucket — and Plexus brings it back into this tab. A message icon in the Review header toggles it on and off. The icon only appears for a session that has a PR, carries a count of the unresolved threads when there are any, and starts out on; your choice then applies to every session and is remembered across restarts.",[10,6642,6643,6644,6647,6648,6650],{},"The PR conversation renders ",[91,6645,6646],{},"beside"," your own notes, never merged into them. Each keeps its own thread, its own author, and its own ",[52,6649,6544],{}," — resolving a PR thread is a public action on the pull request, while resolving one of your notes is private bookkeeping.",[105,6652,6654],{"id":6653},"where-the-comments-appear","Where the comments appear",[331,6656,6657,6679,6732],{},[334,6658,6659,6662,6663,6666,6667,1055,6670,6673,6674,6678],{},[52,6660,6661],{},"Under the diff line they're about."," A thread whose file and line match the current diff renders below that row, under any local notes, on a tinted background. Its header always shows the provider's own ",[22,6664,6665],{},"path:line",", chips for ",[52,6668,6669],{},"Resolved",[52,6671,6672],{},"Outdated",", and a link that opens the thread in your browser. In ",[99,6675,6677],{"href":6676},"#hunks","split view"," a row spans both columns, so its threads sit below the pair — an old-side thread and a new-side one on the same row appear together, each listed once.",[334,6680,6681,6684,6685,1432,6688,1432,6691,1432,6694,6697,6698,6700,6701,6704,6705,853,6707,6709,6710,1055,6713,6716,6717,6719,6721,6722,6724,6725,6728,6729,6731],{},[52,6682,6683],{},"In the Pull request conversation section."," A collapsible section above the diff collects everything that has no home on a line: comments on the pull request itself, review verdicts (",[52,6686,6687],{},"Approved",[52,6689,6690],{},"Changes requested",[52,6692,6693],{},"Dismissed",[52,6695,6696],{},"Commented",") together with the summary the reviewer wrote — a decision left without a summary still appears, as just the reviewer's name and the verdict — threads the provider marked outdated, and threads on files that aren't in the current diff. Nothing is dropped silently — a comment Plexus can't place confidently is listed here instead of guessed onto a line.",[1124,6699],{},"The section ",[52,6702,6703],{},"starts collapsed",", so a busy pull request never buries the diff you came to read. Its header still tells you what's inside without opening it: a count of the items in the section, an ",[52,6706,6687],{},[52,6708,6690],{}," chip when a reviewer left a verdict, a warning triangle when only part of the conversation was fetched, and both ",[52,6711,6712],{},"Comment on the PR",[52,6714,6715],{},"Send N PR comments to agent",". Click the row to open it. Opening is for the visit you're on — leave the tab and come back and the section is closed again, so the diff is always what greets you. Opened, the section never takes more than about 40% of the tab — past that it scrolls while its header stays put, so the diff below it stays on screen.",[1124,6718],{},[52,6720,6712],{}," opens its box in a row of its own, below the section and outside that limit, so writing a comment never competes with the conversation for room — it doesn't open the section either. On a very short window the box gets a scrollbar of its own rather than pushing its own buttons out of reach. Collapsing the section while you write is a way to make room, and your text stays put when you do.",[1124,6723],{},"The verdict chip reports where ",[52,6726,6727],{},"this app"," last saw the review standing, which is not the same as GitHub's merge gate — it doesn't know about required approvals or code owners. Each reviewer's most recent decision counts, so an approval replaces that same reviewer's earlier ",[52,6730,6690],{},", and one reviewer still asking for changes outweighs anyone else's approval. Approving without writing anything counts just the same — it appears as a one-line entry with the reviewer's name and the chip.",[334,6733,6734,6740],{},[52,6735,6736,6737,6739],{},"In the ",[99,6738,6570],{"href":6569},"'s badges."," While the conversation is shown, each file row's two comment badges count the pull request's threads for that file alongside your own notes — open threads in the speech bubble, resolved ones in the check. Hide the conversation and they go back to counting only your notes, so a badge never points at a comment the tab isn't showing you. A thread that no longer lines up with the diff is counted on its file too, and you'll find it in the conversation rather than on a diff line.",[105,6742,6744],{"id":6743},"reply-and-resolve","Reply and resolve",[331,6746,6747,6759,6767],{},[334,6748,6749,6752,6753,6755,6756,6758],{},[52,6750,6751],{},"Reply"," — click ",[52,6754,6751],{}," on a thread, write your answer, and click ",[52,6757,6751],{}," again. It's posted to the pull request as a reply in that thread.",[334,6760,6761,2639,6763,6766],{},[52,6762,6544],{},[52,6764,6765],{},"Unresolve"," — the button is only there when the provider says you're allowed. GitHub permits resolving if you have write access to the repository or you opened the PR, so on someone else's repository you'll see no button rather than one that fails.",[334,6768,6769,6772],{},[52,6770,6771],{},"Open in browser"," — every thread links out to its permalink for anything Plexus doesn't do, such as editing, reactions, or attachments.",[105,6774,6776],{"id":6775},"post-a-new-comment","Post a new comment",[10,6778,6779,6780,6783,6784,6786,6787,6790],{},"Once a PR exists, the line composer grows a target switch. Leave it on ",[52,6781,6782],{},"Note for the agent"," — the default, and exactly what the composer always did — or pick ",[52,6785,6712],{}," to start a new review thread on that line, visible to everyone on the pull request. The button changes to ",[52,6788,6789],{},"Comment",", and Plexus waits for the provider to confirm before the thread appears, so a comment you see is a comment that landed.",[10,6792,6793,6794,6796],{},"The switch appears per comment and always starts on ",[52,6795,6782],{},", so posting publicly is never something you do by carrying over a previous choice.",[105,6798,6800],{"id":6799},"publish-a-note-to-the-pull-request","Publish a note to the pull request",[10,6802,6803,6804,6806,6807,6810],{},"A note you already wrote — or one the ",[99,6805,6268],{"href":6267}," wrote for you — can be published to the pull request after the fact, as an inline comment on the same file and line. It's the other half of ",[99,6808,6776],{"href":6809},"#post-a-new-comment",": that one decides where a comment goes as you write it, this one moves a note you have already read, edited, and decided is worth showing a reviewer.",[331,6812,6813,6825],{},[334,6814,6815,6818,6819,1432,6821,1055,6823,132],{},[52,6816,6817],{},"One note."," The publish button sits in the note's own row of actions, beside ",[52,6820,6541],{},[52,6822,6544],{},[52,6824,3583],{},[334,6826,6827,6830,6831,6834,6835,6838],{},[52,6828,6829],{},"The whole review."," The Review header carries a publish button with a count. It sends the session's ",[52,6832,6833],{},"unresolved"," notes, up to ",[52,6836,6837],{},"40"," at a time — with more than that the dialog says which it will send (\"the first 40 of 57\") rather than truncating silently, and you can publish again for the rest.",[10,6840,6841,6842,6845],{},"Either way, Plexus asks first: a confirmation lists the notes going out and names the repository as ",[22,6843,6844],{},"owner\u002Frepo#number",", so you can see exactly where they're about to land. Nothing reaches the pull request until you confirm.",[10,6847,6848,6849,6852,6853,6855],{},"Both appear only once the pull request's conversation has loaded, only while ",[99,6850,6851],{"href":6173},"PR comments are shown",", and only while the PR is ",[52,6854,2162],{}," — a merged or closed pull request takes no new comments, so the buttons aren't there to offer.",[10,6857,6858,6861,6862,6864],{},[52,6859,6860],{},"Stopping a batch."," While the whole review is going out, the header's publish button turns into a ",[52,6863,4584],{},". It stops at the next note: the one already on its way still lands (and is still consumed), and everything after it is left alone — the same as if the provider had cut the batch short. Publish again when you want the rest.",[10,6866,6867,6870],{},[52,6868,6869],{},"Publishing consumes the note."," When the comment lands, your local note is deleted and the pull request's own thread renders on that line in its place. That's what keeps the two halves of the tab from doubling up, and it means there is no undo from Plexus: edit or delete the comment on GitHub or Bitbucket, the same as any other comment you left there.",[10,6872,6873,5589,6876,6880,6881,6885,6886,6889,6890,132],{},[52,6874,6875],{},"Resolved notes can be published too.",[99,6877,6879],{"href":6878},"#send-comments-to-the-agent","Sending comments to the agent"," resolves everything it sends, and so does each round of the ",[99,6882,6884],{"href":6883},"#review-and-fix-cycle","review-and-fix cycle"," — so the notes most worth showing a reviewer are often exactly the resolved ones. The bulk button is the exception: it sends only what's still unresolved, and it skips notes whose file has left the diff (the ",[99,6887,6888],{"href":6263},"orphaned"," ones), since there's no line left to anchor them to. That's why its count can be lower than the one on ",[52,6891,6615],{},[10,6893,6894,6897,6898,6901,6902,132],{},[52,6895,6896],{},"A note the review agent drafted says so."," Its published comment opens with an italic line — ",[91,6899,6900],{},"Drafted by the Plexus review agent."," — above the note itself, so anyone reading the thread knows the finding came from a model rather than from you. Notes you wrote go out exactly as written, with no marker, the same as ",[52,6903,6712],{},[47,6905,6906,6909],{},[10,6907,6908],{},"A line that isn't part of the pull request's diff yet is refused by the provider — usually because the change is still uncommitted or unpushed. Plexus keeps those notes and tells you which ones didn't land, so you can commit, push, and publish again.",[10,6910,6911],{},"A bulk publish goes out one comment at a time, paced so a large batch doesn't trip the provider's rate limit. If it does hit a rate limit or an authentication problem, it stops there and reports the rest as untried rather than pressing on against a provider that has said no.",[47,6913,6914],{"tone":69},[10,6915,6916],{},"A published comment is public to everyone on the pull request and is posted under your own provider account. The confirmation shows you the exact text and the repository it's going to — read it before you confirm, including anything the review agent wrote for you.",[105,6918,6631],{"id":6919},"send-pr-comments-to-the-agent",[10,6921,6922,6925,6926,6928,6929,6931,6932,6935],{},[52,6923,6924],{},"Send to agent"," on a single thread hands that conversation to the running agent. ",[52,6927,6715],{}," in the conversation header sends every unresolved thread it hasn't sent yet. Either way Plexus folds them into one prompt — introduced as review comments from pull request #N, one entry per thread with its ",[22,6930,6599],{}," and its replies — writes it to the live agent, and switches you to the Agent tab. Threads you've already sent are chipped ",[52,6933,6934],{},"Sent"," so you don't send them twice.",[10,6937,6938,6940],{},[52,6939,6934],{}," lasts as long as the agent that received it. Stop the session, resume it, or lose the agent to a crash, and every thread it was handed becomes sendable again — a prompt written to a terminal that no longer exists was never read, so Plexus stops claiming it was delivered. The header button stays where it is once everything has been sent: it goes quiet and says so, rather than disappearing.",[10,6942,6943,6944,6946],{},"A thread the provider marked outdated or resolved carries that word in the prompt, next to its ",[22,6945,6599],{},", so the agent gets the same caveat you do: an outdated line number points at whatever code sits there now.",[10,6948,6949,6950,6953,6954,6956,6957,6959],{},"Sending changes nothing on GitHub or Bitbucket. If you'd like those threads resolved once the agent has worked on them, turn on ",[52,6951,6952],{},"Resolve PR comments after the agent fixes them"," (Settings → Git & PRs, default ",[52,6955,5652],{},"); see ",[99,6958,102],{"href":101},". It resolves a thread only if the agent that was given it finishes the turn — resuming the session drops anything the previous agent never saw.",[10,6961,6962,6963,6966,6967,6969],{},"One prompt carries a bounded amount of conversation, so a very busy pull request doesn't bury the ask in a wall of quoted text. If a send doesn't fit, the prompt ends with ",[22,6964,6965],{},"… N more comments not included"," — the threads it left out stay unsent (no ",[52,6968,6934],{}," chip), so sending again picks up where it stopped.",[47,6971,6972],{"tone":69},[10,6973,6974],{},"That setting resolves the threads the moment the agent's turn ends. That's a claim that the agent finished, not that the change is correct or pushed — you still review the diff and push it yourself. Resolving is visible to the PR's author and its other reviewers, which is why nothing else in Plexus ever does it for you.",[105,6976,6978],{"id":6977},"keeping-them-up-to-date","Keeping them up to date",[10,6980,6981,6982,6984,6985,6987],{},"Plexus fetches the conversation when you open the Review tab, when the Plexus window regains focus, and when you click ",[52,6983,1165],{}," — there's no background polling, so reading a review never costs you a request you didn't ask for. Reopening the tab within a short window reuses what was already fetched; ",[52,6986,1165],{}," always goes to the provider.",[105,6989,6991],{"id":6990},"what-to-expect","What to expect",[331,6993,6994,7010,7020,7026,7032,7038],{},[334,6995,6996,6999,7000,7002,7003,7006,7007,7009],{},[52,6997,6998],{},"Line anchors are advisory."," This tab diffs your ",[91,7001,1651],{},", while the pull request anchors its comments to its ",[91,7004,7005],{},"head commit",". Uncommitted or unpushed work can shift a line by a few, so every thread prints the provider's own ",[22,7008,6665],{}," next to the code — compare the two if a comment reads oddly against the line it's sitting on.",[334,7011,7012,7015,7016,7019],{},[52,7013,7014],{},"An inline comment has to land on a line that's part of the PR's diff."," GitHub rejects anything else; when that happens Plexus says so and suggests committing and pushing first, or commenting on the PR conversation instead. The same applies to a ",[99,7017,7018],{"href":6580},"published note",", which is kept locally when the provider refuses it.",[334,7021,7022,7025],{},[52,7023,7024],{},"Pull requests opened from a fork aren't supported yet."," Plexus looks for the pull request on the repository itself, so a PR whose branch lives in a fork isn't found and no comments appear for it.",[334,7027,7028,7031],{},[52,7029,7030],{},"Images in comments aren't loaded."," Comment bodies render as markdown with remote images stripped, so opening a review never fetches anything from a third-party host. Open the thread in your browser to see them.",[334,7033,7034,7037],{},[52,7035,7036],{},"Very busy pull requests are fetched up to a limit."," If it's reached, the conversation section's header carries a warning triangle even while it's collapsed, and the section itself says only part was fetched and links you out for the rest.",[334,7039,7040,7043,7044,2639,7046,7048],{},[52,7041,7042],{},"Bitbucket has no review verdicts."," Its reviewers leave ordinary comments, so those arrive as PR-level threads rather than as ",[52,7045,6687],{},[52,7047,6690],{}," entries.",[14,7050,6268],{"id":7051},"ai-review",[10,7053,4123,7054,7057],{},[52,7055,7056],{},"Run AI review"," to hand the diff to a headless Claude instance that reviews it for bugs, security issues, and risky changes, then posts inline comments as the Plexus Review Agent. A spinner shows while it runs — anywhere from under a minute to several, depending on the size of the diff, the length of your review instructions, and which model and effort level it resolves to. When it finishes, a banner reports how many comments were added. Treat them like your own — edit, resolve, or send them to the interactive agent.",[105,7059,7061],{"id":7060},"customize-the-review-prompt","Customize the review prompt",[10,7063,7064,7065,7068,7069,7071],{},"The brief the reviewer follows is fully yours. The ",[52,7066,7067],{},"AI code-review instructions"," setting (Settings → Git & PRs) ",[91,7070,5228],{}," the review instruction — it decides what the model looks for and how to weigh it. The default reads:",[10,7073,7074],{},[91,7075,7076],{},"You are a senior engineer reviewing this pull request diff. Flag correctness bugs, security issues, and risky changes as concise, actionable inline comments. Do not rewrite the code.",[10,7078,7079,7080,7083,7084,502],{},"Replace it with whatever fits: focus on your project's conventions, ignore a class of issue, enforce a style guide, or even ask for the comments in another language. Set it once globally for every repository, or override it per ",[99,7081,7082],{"href":323},"workspace or project"," so each codebase gets its own reviewer (see ",[99,7085,102],{"href":101},[47,7087,7088,7099],{},[10,7089,7090,7091,7094,7095,7098],{},"You never have to spell out a response format. Plexus wraps your prompt with the diff — every line tagged with its file, side, and line number — and hands the model a strict output schema, then turns the reply into comments anchored to the exact lines. The schema isn't a request: it constrains what the model is able to produce, so the reply comes back in the right shape even if your instructions invite prose or your global Claude Code setup would otherwise reshape the answer. Your prompt decides ",[91,7092,7093],{},"what"," gets reviewed; Plexus guarantees ",[91,7096,7097],{},"how"," the results come back, so a custom prompt can't misplace or break comments.",[10,7100,7101,7102,7105],{},"If a reply is cut short — a very large diff can hit the model's output limit — Plexus keeps every complete comment rather than discarding the batch, and it still retries once if a reply can't be read at all. When one can't, the result banner offers ",[52,7103,7104],{},"Copy reply",", which gives you the reply as it arrived (very long ones are trimmed, with a note saying how much was left out).",[14,7107,7109],{"id":7108},"review-and-fix-cycle","Review-and-fix cycle",[10,7111,2199,7112,7115,7116,7119,7120,7122],{},[52,7113,7114],{},"Review and fix cycle"," automates the whole loop unattended: it runs an AI review, spawns a separate headless agent to apply the fixes, waits for it to finish, then re-reviews — repeating until the review finds no issues or it hits the round limit. Each round that actually runs resolves the comments it handed to the fix agent, exactly as a manual ",[99,7117,7118],{"href":6878},"send"," does, so when it's over the ",[99,7121,6570],{"href":6569}," reads as a count of resolved comments per file — a record of what the cycle worked on, rather than a sidebar back to blank. A round whose agent never started leaves its comments open instead, so nothing is marked done on the strength of work that didn't happen.",[331,7124,7125,7131,7142,7151,7164,7173],{},[334,7126,7127,7130],{},[52,7128,7129],{},"Consent (once per repository)."," The first run for a repository opens a dialog explaining that the cycle runs an unattended, non-sandboxed agent that can edit files without approval. Confirm to proceed; each repository is treated independently.",[334,7132,7133,7136,7137,853,7139,132],{},[52,7134,7135],{},"Activity warning."," If the interactive agent still looks mid-turn, a dialog warns the two agents could conflict in the same worktree. The signal is best-effort, so you can ",[52,7138,1186],{},[52,7140,7141],{},"Start anyway",[334,7143,7144,7147,7148,7150],{},[52,7145,7146],{},"Status strip."," While the cycle runs, a strip below the file list shows the current round and phase (reviewing or fixing), then the terminal result. A ",[52,7149,4584],{}," button halts it gracefully at any time.",[334,7152,7153,7156,7157,7160,7161,7163],{},[52,7154,7155],{},"Watch the agent."," A cycle can run for a long time, so ",[52,7158,7159],{},"Watch agent"," — in the status strip and in the session header, alongside ",[52,7162,4584],{}," — opens a panel at the bottom of the session. The top half is a running account of the cycle: which round it is on, how many files the review is reading, when it asked the model, how many comments came back, and how long each phase took. The bottom half is a live, read-only terminal on the fix agent itself, so you can see exactly what it is editing. Both buttons appear only while a cycle is running; the panel has its own close button, so it stays open on the finished round until you dismiss it.",[334,7165,7166,7169,7170,7172],{},[52,7167,7168],{},"A failed round doesn't end the run."," If a review round fails for a passing reason — the model is rate-limited or overloaded, or its reply couldn't be read — the cycle notes it, skips that round, and reviews again on the next one. Only a failure that can't improve on retry (the ",[22,7171,24],{}," CLI isn't installed) stops it immediately. A failed review is never reported as \"no issues remain\", so the cycle can't finish clean on a round that didn't actually run.",[334,7174,7175,7178,7179,7182],{},[52,7176,7177],{},"A fix agent that never starts is retried, but two failures in a row end the cycle."," A fix agent can launch and never get going, or die the moment it starts. The cycle notices either within about a minute, stops that agent, and retries the round rather than waiting on it. As with a skipped review, a round whose agent never ran is not counted as a fix round in the result — and its comments stay open, so the next round can hand them over again. If two rounds in a row fail to start, the cycle stops there and says so: nothing changed between the attempts, so further rounds would only spend time and usage on the same outcome. The count is of ",[91,7180,7181],{},"consecutive"," failures and resets on any round that runs, so an occasional failure between working rounds just gets retried.",[47,7184,7185,7191],{},[10,7186,7187,7190],{},[52,7188,7189],{},"What the panel does and doesn't keep."," The fix agent's output stays inside Plexus and is never written to disk. It only reaches the app while the panel is open — closing it stops the stream at the source rather than merely hiding it — and opening it mid-round back-fills the most recent stretch of output so you aren't starting from blank. The terminal is strictly read-only: you can select and copy from it, but you can't type into the agent, which also means a stray keystroke can't interrupt a round.",[10,7192,7193,7196],{},[52,7194,7195],{},"Only the fix half has a terminal."," The review itself doesn't run in one, so during a reviewing phase the panel says so and the account above it carries the narrative instead.",[47,7198,7199,7206],{"tone":69},[10,7200,7201,7202,7205],{},"The cycle stops after the ",[52,7203,7204],{},"Review-and-fix round limit"," (Settings → Git & PRs, default 10). It requires a session worktree and refuses to run on root-tree sessions, so it never edits your project's real checkout.",[10,7207,7208,7209,7211],{},"On a session started on an ",[99,7210,6256],{"href":1269},", give it a second thought: this is an unattended agent editing a branch other people may also be working on. It stays on your machine either way — Plexus never pushes for you — so read the result before it goes anywhere.",[105,7213,7215],{"id":7214},"if-rounds-are-taking-too-long","If rounds are taking too long",[10,7217,7218],{},"A round is a full AI review plus a complete agent session that edits your files, so tens of minutes per round is normal rather than a fault. The panel's per-phase timings tell you which half is spending the time, and there are four settings for it (all Settings → Git & PRs, all overridable per workspace or project):",[331,7220,7221,7230],{},[334,7222,7223,1055,7226,7229],{},[52,7224,7225],{},"Model for the review-and-fix agent",[52,7227,7228],{},"Effort for the review-and-fix agent"," — the fix half is usually the larger share, and by default both are left to whatever your Claude Code configuration resolves to. If that is a large model at a high effort level, every round inherits it. Pinning them here is the biggest single lever.",[334,7231,7232,1055,7235,7238],{},[52,7233,7234],{},"Model for AI code review",[52,7236,7237],{},"Effort for AI code review"," — the review is one pass that reads a diff and returns comments in a fixed shape, so it tolerates a lower setting better than the fix agent does.",[10,7240,7241,7242,7244,7245,7248],{},"Two other things are worth a look. Very long ",[52,7243,7067],{}," are re-sent in full on every round, so a prompt that has grown to thousands of words is paid for repeatedly. And if the fix agent is doing more than the comments asked — reformatting, updating documentation, running whole test suites — that usually comes from instructions in the repository's own agent configuration file rather than from Plexus; ",[52,7246,7247],{},"Review-and-fix agent instructions"," is where you tell it to stay on task.",[14,7250,7252],{"id":7251},"refreshing-the-diff","Refreshing the diff",[10,7254,7255],{},"Returning to a session renders the Review tab instantly from cache while it revalidates in the background, so edits that landed while you were away heal automatically. The cache also invalidates when an agent turn finishes or you run a git operation, keeping the diff in sync without any action from you.",[10,7257,4123,7258,7260,7261,7264],{},[52,7259,1165],{}," to force a guaranteed-fresh fetch from disk. If the base branch has an upstream, Refresh also runs a ",[22,7262,7263],{},"git fetch"," to pull the latest remote base before comparing.",[14,7266,2343],{"id":2342},[331,7268,7269,7274,7279],{},[334,7270,7271,7273],{},[99,7272,136],{"href":368}," — stage, commit, and run git operations on the worktree.",[334,7275,7276,7278],{},[99,7277,2655],{"href":1469}," — open a PR from a session and track its status and CI.",[334,7280,7281,4007,7283,1432,7285,1432,7287,7289],{},[99,7282,102],{"href":101},[52,7284,7067],{},[52,7286,7204],{},[52,7288,6952],{},", and more.",{"title":33,"searchDepth":266,"depth":266,"links":7291},[7292,7296,7297,7298,7299,7300,7309,7312,7315,7316],{"id":6108,"depth":266,"text":6109,"children":7293},[7294,7295],{"id":6140,"depth":271,"text":6141},{"id":6191,"depth":271,"text":6192},{"id":6249,"depth":266,"text":6250},{"id":5893,"depth":266,"text":5841},{"id":6530,"depth":266,"text":6531},{"id":6608,"depth":266,"text":6609},{"id":6634,"depth":266,"text":6587,"children":7301},[7302,7303,7304,7305,7306,7307,7308],{"id":6653,"depth":271,"text":6654},{"id":6743,"depth":271,"text":6744},{"id":6775,"depth":271,"text":6776},{"id":6799,"depth":271,"text":6800},{"id":6919,"depth":271,"text":6631},{"id":6977,"depth":271,"text":6978},{"id":6990,"depth":271,"text":6991},{"id":7051,"depth":266,"text":6268,"children":7310},[7311],{"id":7060,"depth":271,"text":7061},{"id":7108,"depth":266,"text":7109,"children":7313},[7314],{"id":7214,"depth":271,"text":7215},{"id":7251,"depth":266,"text":7252},{"id":2342,"depth":266,"text":2343},"See exactly what an agent changed, iterate with inline comments, and read and answer your pull request's review conversation without leaving Plexus.","GitPullRequestArrow",{},24,{"title":6100,"description":7317},"docs\u002Freview","vGv_6n-rQ98ASaPyVyCqbj1fYxgUT9z2vEZEbbQ31KE",{"id":7325,"title":4432,"body":7326,"description":7789,"extension":277,"group":5019,"icon":7790,"meta":7791,"navTitle":3988,"navigation":281,"order":7792,"path":368,"seo":7793,"stem":7794,"__hash__":7795},"docs\u002Fdocs\u002Fgit.md",{"type":7,"value":7327,"toc":7776},[7328,7333,7340,7344,7353,7362,7368,7386,7389,7403,7416,7428,7430,7447,7453,7456,7462,7478,7491,7494,7503,7517,7521,7545,7569,7573,7586,7589,7605,7625,7647,7655,7659,7671,7684,7690,7696,7709,7718,7722,7729,7749,7752,7754],[10,7329,7330,7331,132],{},"The Git tab is a full git client for the session's worktree — browse history, stage and commit, stash, push, and reshape the branch without leaving Plexus. It is scoped to the one session's worktree and branch; for the repository itself — the commit graph, branch management, and the project's main checkout — use the ",[99,7332,2381],{"href":373},[10,7334,2067,7335,7337,7338,2399],{},[22,7336,1981],{}," to open it. The left pane is the commit log; the right pane shows either the commit you selected or the staging panel for uncommitted work. Throughout this page ",[22,7339,1996],{},[14,7341,7343],{"id":7342},"commit-history","Commit history",[10,7345,7346,7347,7349,7350,7352],{},"The left pane lists the branch's commits newest-first. A divider labeled ",[52,7348,4469],{}," marks the merge-base — commits above it are unique to this session's branch, commits below are shared with the base. When history runs deeper than the current page, click ",[52,7351,2503],{}," to fetch earlier commits.",[10,7354,7355,7356,7358,7359,7361],{},"Click any commit to open its detail view: the full message, author, timestamp, and the changed files. Click a file to see its read-only diff — unified or side-by-side, following the ",[52,7357,2739],{}," toggle above it, which shares its setting with the ",[99,7360,1435],{"href":358},"; binary and oversized files show a placeholder instead of hunks. Merge commits are badged as such.",[10,7363,7364],{},[1096,7365],{"alt":7366,"src":7367},"The Git tab: the commit log with the base divider on the left, and the selected commit's message, author, and file diff on the right.","\u002Fdocs\u002Fgit.png",[10,7369,7370,7371,7374,7375,7378,7379,7382,7383,7385],{},"To undo a commit, click ",[52,7372,7373],{},"Revert"," in its detail view. Plexus runs ",[22,7376,7377],{},"git revert"," (with ",[22,7380,7381],{},"-m 1"," for merge commits) and lands a new revert commit on top — your history stays intact. If the revert conflicts, resolve the markers in the ",[99,7384,1431],{"href":1430}," and the log refreshes.",[14,7387,2668],{"id":7388},"uncommitted-changes",[10,7390,2199,7391,7393,7394,1432,7396,1432,7398,1439,7400,7402],{},[52,7392,2668],{}," node is pinned at the top of the commit list. Click it to open the staging panel, grouped into collapsible ",[52,7395,3337],{},[52,7397,3340],{},[52,7399,3343],{},[52,7401,2794],{}," sections. Click any staged or unstaged file to view its working-tree diff on the right; untracked files render their full contents as added lines.",[10,7404,7405,7406,2639,7409,7412,7413,7415],{},"Hover a file to reveal a quick stage\u002Funstage icon, or use the section headers' ",[52,7407,7408],{},"Stage all",[52,7410,7411],{},"Unstage all"," buttons. ",[52,7414,7408],{}," includes untracked files.",[47,7417,7418],{"tone":69},[10,7419,7420,7421,7424,7425,7427],{},"Conflicted files carry a ",[22,7422,7423],{},"!"," badge and cannot be staged. Resolve the conflict in the ",[99,7426,1431],{"href":1430}," first — once the markers are gone, the file moves to a stageable section.",[105,7429,3361],{"id":3360},[10,7431,7432,7433,7435,7436,7438,7439,7441,7442,7444,7445,132],{},"To throw away uncommitted edits, right-click a changed file and choose ",[52,7434,3373],{},", or select files and use the panel header. Selection works like a file manager: click a file to select just it, ",[52,7437,3377],{}," to add or remove individual files, and ",[52,7440,3381],{}," to select the range from the last-clicked file. Once at least one file is selected, a ",[52,7443,3388],{}," button appears next to ",[52,7446,3138],{},[10,7448,7449,7450,7452],{},"Right-clicking a file that's already part of your selection acts on all of it — the menu entry says which, reading ",[52,7451,3392],{}," — while right-clicking outside the selection selects just that file first. The same menu stages or unstages the one file you clicked, and copies its path.",[10,7454,7455],{},"Discard returns each selected file to its committed state — modified and deleted files revert to the last commit, dropping both staged and unstaged changes. Conflicted files aren't part of the selection; resolve them in the Agent tab instead.",[10,7457,7458,7459,7461],{},"With nothing selected, the header offers ",[52,7460,3406],{}," instead: every tracked file goes back to the last commit, and unless you turn the switch off in the dialog, every new file is deleted from disk — including new files you've already staged. Empty folders left behind by those files go too. It refuses while a merge or rebase is in progress; finish or abort that first.",[47,7463,7464],{"tone":69},[10,7465,7466,7467,7470,7471,7474,7475,7477],{},"Discarding a ",[52,7468,7469],{},"new or untracked"," file ",[52,7472,7473],{},"deletes it from disk"," — there is no committed version to restore, and this can't be undone. A confirmation dialog lists every affected file before anything is removed, so you can catch a wrong selection first. Nothing is stashed on your behalf — if you might want the changes back, use ",[52,7476,3138],{}," instead.",[47,7479,7480],{},[10,7481,3437,7482,3441,7484,7486,7487,3456,7489,3461],{},[22,7483,3440],{},[52,7485,3444],{}," touched, by any of these. Since ignored files never appear in the file list, a confirmation couldn't show you what it was about to delete, so Plexus doesn't offer it — run ",[22,7488,3455],{},[99,7490,4062],{"href":1969},[105,7492,3492],{"id":7493},"commit",[10,7495,7496,7497,7499,7500,7502],{},"With files staged, write a message in the composer and click ",[52,7498,3492],{}," (or press ",[22,7501,5670],{}," from the message field). Only staged files are committed; the button stays disabled until something is staged and a title is entered. On success the log and panel refresh.",[10,7504,4135,7505,7507,7508,7511,7512,7514,7515,132],{},[52,7506,3484],{}," button to draft a message from the staged diff — a concise imperative subject and an optional body explaining the ",[91,7509,7510],{},"why",". Edit both before committing. Tune the drafting instruction with the ",[52,7513,3488],{}," setting (Settings → Git & PRs); see ",[99,7516,102],{"href":101},[105,7518,7520],{"id":7519},"stash-and-push","Stash and push",[10,7522,7523,7525,7526,7528,7529,7531,7532,7534,7535,7537,7538,7540,7541,7544],{},[52,7524,3138],{}," saves all changes — staged, unstaged, and untracked — onto the stash; saved entries appear under ",[52,7527,2794],{},", where ",[52,7530,2891],{}," restores one. Click a stash entry to open it: the sidebar becomes the list of files it changed — tracked and untracked alike — and clicking a file shows its diff on the right. The opened stash offers four actions — ",[52,7533,2888],{}," restores the stashed changes but keeps the entry, ",[52,7536,2891],{}," restores them and removes the entry, ",[52,7539,3583],{}," drops the entry without restoring it (after a confirmation), and ",[52,7542,7543],{},"Close"," returns to the working-tree view. A conflicting pop keeps the stash intact and surfaces the conflict.",[10,7546,7547,7549,7550,7552,7553,7556,7557,7560,7561,7563,7564,7566,7567,132],{},[52,7548,2576],{}," sends the branch to ",[22,7551,2783],{}," (non-force, with ",[22,7554,7555],{},"-u","). It is disabled when ",[22,7558,7559],{},"HEAD"," is detached or the branch has no name. Git rejects a non-fast-forward push, so if you rebased or squashed after a prior push you'll need to force-push from the command line — Plexus does not offer that by design. It authenticates with your own git credentials, falling back to a ",[99,7562,3166],{"href":3165}," when your machine has none for an ",[22,7565,1200],{}," remote. To open a pull request once the branch is pushed, see ",[99,7568,2655],{"href":1469},[14,7570,7572],{"id":7571},"branch-operations","Branch operations",[10,7574,7575,7576,7578,7579,7581,7582,7585],{},"Three operations reshape the session branch in place — whichever branch that is: the ",[22,7577,4800],{}," branch Plexus cut for the session, or the ",[99,7580,6256],{"href":1269}," it was started on. Because they rewrite history, each requires ",[52,7583,7584],{},"two"," modifiers to prevent accidental fires:",[1365,7587],{":rows":7588},"[[\"⌘4\",\"Switch to the Git tab\"],[\"⌘⌥R\",\"Rebase the branch onto its base (linear, no merge commit)\"],[\"⌘⌥M\",\"Merge the base into the branch (--no-ff merge commit)\"],[\"⌘⌥S\",\"Squash all commits since the merge-base into one\"],[\"⌘Enter\",\"Commit staged changes from the composer\"]]",[10,7590,7591,7592,7594,7595,853,7601,7604],{},"Rebase and merge fetch the base from ",[22,7593,2783],{}," first when it exists remotely, so the session catches up with work that landed after it started. Each operation toasts its result — for example ",[91,7596,7597,7598],{},"Rebased onto ",[22,7599,7600],{},"\u003Cbase>",[91,7602,7603],{},"Already up to date",". These reshape the session branch only; they do not integrate your work into the trunk.",[47,7606,7607],{"tone":69},[10,7608,7609,1055,7611,7614,7615,7617,7618,7621,7622,7624],{},[52,7610,3098],{},[52,7612,7613],{},"Squash"," rewrite history. On a ",[22,7616,4800],{}," branch Plexus cut for the session that's a private affair — nobody else has those commits. On a branch the session was ",[91,7619,7620],{},"started on",", they may already be pushed and sitting in someone else's checkout, and rewriting them makes your copy and theirs disagree. Plexus warns rather than refusing — you may well be the person who should rewrite it — and its ",[52,7623,2576],{}," is never a force-push, so git rejects the next push instead of overwriting anyone's work. A rewrite therefore stays on your machine until you resolve it deliberately.",[10,7626,7627,7628,7630,7631,7633,7634,7636,7637,7640,7641,7644,7645,132],{},"If that fetch fails — you're offline, the VPN is down, your machine has no credentials for the remote (and no ",[99,7629,3166],{"href":3165}," that covers it), or the remote doesn't answer within two minutes — the operation is ",[52,7632,168],{}," cancelled. Plexus reshapes onto the last version of the base branch it fetched and adds a warning saying so, so a ",[91,7635,7603],{}," never quietly means ",[91,7638,7639],{},"couldn't check",". To skip the fetch entirely, turn off ",[52,7642,7643],{},"Fetch the base branch before rebasing or merging"," (Settings → Git & PRs, per project if you like); with it off the reshape uses the copy of the base branch already on your machine and makes no network request at all. See ",[99,7646,102],{"href":101},[47,7648,7649],{},[10,7650,7651,7652,7654],{},"Rebinding any reshape shortcut to a single-modifier key is rejected by settings validation. See ",[99,7653,2000],{"href":1476}," to view or change the bindings.",[105,7656,7658],{"id":7657},"when-a-rebase-is-worth-doing","When a rebase is worth doing",[10,7660,7661,7662,7664,7665,7670],{},"While a session works, the branch it was cut from keeps moving — and you shouldn't have to run a rebase just to find out whether one was needed. When the base branch has commits this session's branch doesn't, an amber badge — a rebase arrow and a number — appears next to the ",[52,7663,136],{}," button in the session's header, and the ",[52,7666,7667,7668],{},"Rebase onto ",[22,7669,7600],{}," item inside that menu shows the same number.",[10,7672,7673,7674,7677,7678,7680,7681,7683],{},"The number means one specific thing: ",[52,7675,7676],{},"a rebase onto the base branch would bring in that many commits."," It's counted against the very ref the rebase itself uses — ",[22,7679,6127],{}," when the base exists on your remote, the local ",[22,7682,7600],{}," branch otherwise — so the badge never points you at a rebase that would turn out to do nothing.",[10,7685,7686,7687,7689],{},"It is a signpost, not a button. Clicking ",[52,7688,136],{}," just opens the menu, exactly as before: a rebase rewrites history, so starting one stays an explicit choice.",[10,7691,7692,7693,7695],{},"You see no badge at all — not a zero — when there's nothing to bring in, and equally when Plexus can't work the number out: the session has no base branch, a rebase, merge, cherry-pick, or revert is already in progress in its worktree, ",[22,7694,7559],{}," is detached, the base branch no longer exists, or the two branches share no history.",[47,7697,7698],{},[10,7699,7700,7701,7704,7705,7708],{},"The count is read from what your machine has ",[52,7702,7703],{},"already"," downloaded — Plexus makes no extra network request for it — so it is only as fresh as your last fetch. With ",[99,7706,2485],{"href":7707},"\u002Fdocs\u002Fproject-git#automatic-fetching"," on and the default intervals, that's about every ten minutes for a project whose Git tab isn't open, and about once a minute for the one that is; the badge's tooltip says how long ago that fetch was — or that nothing has fetched yet. With automatic fetching turned off, the count only moves when something else fetches.",[10,7710,7711,7712,7715,7716,132],{},"Beyond that, the badge re-checks itself whenever your refs actually change, when a git operation in the session finishes, at the end of an agent turn, and when you return to the Plexus window. To hide it entirely, turn off ",[52,7713,7714],{},"Suggest a rebase when the base branch moves ahead"," (Settings → Git & PRs); see ",[99,7717,102],{"href":101},[105,7719,7721],{"id":7720},"dirty-worktree","Dirty worktree",[10,7723,7724,7725,7728],{},"If you trigger a rebase or merge with uncommitted changes, a ",[52,7726,7727],{},"Resolve dirty worktree"," dialog appears first with three choices:",[331,7730,7731,7737,7743],{},[334,7732,7733,7736],{},[52,7734,7735],{},"Commit & continue"," — commit the changes (optionally with a message you provide), then run the operation.",[334,7738,7739,7742],{},[52,7740,7741],{},"Stash & continue"," — stash the changes; they stay stashed after the reshape.",[334,7744,7745,7748],{},[52,7746,7747],{},"Stash & pop"," — stash, run the reshape, then attempt to restore the stashed changes.",[10,7750,7751],{},"Once the tree is clean the original operation runs, and any resulting conflicts appear in the conflict dialog.",[14,7753,2343],{"id":2342},[331,7755,7756,7761,7766,7771],{},[334,7757,7758,7760],{},[99,7759,2381],{"href":373}," — the project-level git client: commit graph, branches, and the main checkout.",[334,7762,7763,7765],{},[99,7764,359],{"href":358}," — read the branch's full diff against its base before you commit or open a PR.",[334,7767,7768,7770],{},[99,7769,2655],{"href":1469}," — push the branch and open a GitHub PR.",[334,7772,7773,7775],{},[99,7774,2000],{"href":1476}," — the full list of rebindable git shortcuts.",{"title":33,"searchDepth":266,"depth":266,"links":7777},[7778,7779,7784,7788],{"id":7342,"depth":266,"text":7343},{"id":7388,"depth":266,"text":2668,"children":7780},[7781,7782,7783],{"id":3360,"depth":271,"text":3361},{"id":7493,"depth":271,"text":3492},{"id":7519,"depth":271,"text":7520},{"id":7571,"depth":266,"text":7572,"children":7785},[7786,7787],{"id":7657,"depth":271,"text":7658},{"id":7720,"depth":271,"text":7721},{"id":2342,"depth":266,"text":2343},"The full git workflow — commits, stash, push, rebase, squash — one keystroke away.","GitMerge",{},25,{"title":4432,"description":7789},"docs\u002Fgit","pBzddePn3IxMjaPHMic-s3psjVFaHM8dexGqUAtG020",{"id":7797,"title":2655,"body":7798,"description":8058,"extension":277,"group":5019,"icon":8059,"meta":8060,"navTitle":2655,"navigation":281,"order":8061,"path":1469,"seo":8062,"stem":8063,"__hash__":8064},"docs\u002Fdocs\u002Fpull-requests.md",{"type":7,"value":7799,"toc":8048},[7800,7803,7812,7816,7826,7829,7833,7850,7856,7860,7867,7871,7878,7882,7885,7919,7926,7934,7948,7952,7959,7967,7980,7984,7991,8027,8032],[10,7801,7802],{},"Open a pull request straight from a session's branch and watch its status — open, merged, or closed, plus CI — without leaving Plexus.",[47,7804,7805],{},[10,7806,7807,7808,1751,7810,132],{},"GitHub and Bitbucket are both supported. Connect either one from ",[52,7809,156],{},[99,7811,173],{"href":172},[14,7813,7815],{"id":7814},"before-you-start","Before you start",[10,7817,7818,7819,157,7821,7823,7824,132],{},"PR features need a connected git provider. Open ",[52,7820,156],{},[52,7822,160],{}," for GitHub or Bitbucket — a one-click sign-in, no CLI required. Plexus stores the resulting token in your OS keychain and talks to the provider directly from your machine; the token is never sent to us. See ",[99,7825,173],{"href":172},[10,7827,7828],{},"A session also has to be on a named feature branch with at least one commit beyond its base. Sessions on the project's main branch can't open a PR.",[14,7830,7832],{"id":7831},"create-a-pull-request","Create a pull request",[1114,7834,7835,7843,7846],{},[334,7836,7837,7838,4529,7840,132],{},"On the session row, open the ",[52,7839,1083],{},[52,7841,7842],{},"Create PR",[334,7844,7845],{},"Fill in the title, an optional description, and an optional base branch.",[334,7847,4123,7848,132],{},[52,7849,4249],{},[10,7851,7852,7853,7855],{},"Plexus pushes the branch to ",[22,7854,2783],{},", opens the PR on your provider (GitHub or Bitbucket), and the session's branch icon turns green.",[105,7857,7859],{"id":7858},"a-dirty-worktree","A dirty worktree",[10,7861,7862,7863,7866],{},"If the worktree has uncommitted changes when you create a PR, Plexus doesn't fail — it shows a commit-then-PR dialog. Enter a commit message (or accept the default ",[22,7864,7865],{},"WIP on \u003Cbranch>","), and Plexus commits, pushes, and opens the PR in one flow.",[105,7868,7870],{"id":7869},"auto-generate-the-title-and-description","Auto-generate the title and description",[10,7872,7873,7874,7877],{},"Turn on ",[52,7875,7876],{},"Write pull request descriptions with AI"," (Settings → Git & PRs, default off) to have the agent draft the PR title and description from the diff when the dialog opens. It spends an AI turn, and you can still edit the draft before submitting.",[14,7879,7881],{"id":7880},"track-pr-status","Track PR status",[10,7883,7884],{},"Once a PR exists, the branch icon next to the session reflects its state at a glance:",[190,7886,7887,7896],{},[193,7888,7889],{},[196,7890,7891,7894],{},[199,7892,7893],{},"Icon color",[199,7895,5313],{},[209,7897,7898,7905,7912],{},[196,7899,7900,7902],{},[214,7901,1731],{},[214,7903,7904],{},"No PR (or the PR was closed without merging)",[196,7906,7907,7909],{},[214,7908,1737],{},[214,7910,7911],{},"PR is open",[196,7913,7914,7916],{},[214,7915,1743],{},[214,7917,7918],{},"PR is merged",[10,7920,7921,7922,7925],{},"Hover the icon for details, including the aggregate ",[52,7923,7924],{},"CI status"," (pending, passing, or failing) from the provider's checks (GitHub check runs \u002F Bitbucket pipelines). Click a green or purple icon to open the PR in your browser.",[10,7927,7928,7929,7931,7932,132],{},"Status is polled automatically — when you focus the window, on a periodic refresh, and when the agent finishes a turn. You can also refresh on demand from the session ",[52,7930,1083],{}," menu. CI status updates alongside the PR, so a very fast pipeline may briefly show \"pending\" until the next refresh. For how the branch and activity indicators relate, see ",[99,7933,1362],{"href":348},[47,7935,7936,7939],{},[10,7937,7938],{},"A one-off network hiccup is ignored quietly, but if the status genuinely can't keep updating, Plexus tells you once, with the reason, rather than leaving the icon silently stale.",[10,7940,7941,7942,7944,7945,7947],{},"If the reason is a credentials or rate-limit problem, Plexus also slows that session's automatic polling down, because with a rate limit it's the repeated requests themselves that keep it in place. After you reconnect, automatic updates resume within a few minutes — or hit ",[52,7943,1165],{}," in the session ",[52,7946,1083],{}," menu for an immediate answer.",[14,7949,7951],{"id":7950},"review-comments","Review comments",[10,7953,7954,7955,7958],{},"Once the PR exists, its review conversation lives on GitHub or Bitbucket — and the ",[99,7956,1435],{"href":7957},"\u002Fdocs\u002Freview#pull-request-comments"," shows it. A toggle in the Review header reveals the PR's threads under the diff lines they're about, with everything that can't be placed on the current diff (PR-level comments, review verdicts, outdated threads) collected in a section of its own — one that starts collapsed, with a count and any review verdict in its header. From there you can reply, resolve a thread when the provider allows it, post a new comment on a line, and hand one thread — or all of them — to the agent as a prompt.",[10,7960,7961,7962,7966],{},"Your own inline notes can travel the other way while the PR is open: ",[99,7963,7965],{"href":7964},"\u002Fdocs\u002Freview#publish-a-note-to-the-pull-request","publish one"," — or the session's unresolved set in one go — and it's posted as an inline comment on the same line under your provider account, replacing the local note.",[10,7968,7969,7970,7973,7974,7976,7977,7979],{},"Unlike the status above, the conversation is ",[52,7971,7972],{},"not polled",". Plexus fetches it when you open the Review tab, when the window regains focus, and when you click ",[52,7975,1165],{}," — never in the background. See ",[99,7978,6587],{"href":7957}," for the full flow and its limits.",[14,7981,7983],{"id":7982},"after-the-pr-is-created","After the PR is created",[10,7985,7986,7987,7990],{},"Two optional behaviors keep ",[99,7988,7989],{"href":1293},"sessions"," tidy as PRs progress:",[331,7992,7993,8002],{},[334,7994,7995,4007,7998,8001],{},[52,7996,7997],{},"Auto-rename from PR title",[52,7999,8000],{},"Rename sessions to match their pull request"," (Settings → Git & PRs, default on) keeps the session name in sync with the PR title. The underlying git branch keeps its original name.",[334,8003,8004,4007,8007,8010,8011,8013,8014,8016,8017,8020,8021,8023,8024,8026],{},[52,8005,8006],{},"Auto-teardown on merge",[52,8008,8009],{},"Clean up a session when its pull request is merged"," (Settings → Git & PRs, default off) tears the session down when Plexus detects its PR has merged. It honors your ",[52,8012,4910],{}," setting, so it archives or deletes per your configuration — but it never asks. Nobody is at the keyboard when a background check notices the merge, and switching this on is the confirmation, so ",[52,8015,4956],{}," deletes here too. Whether the branch goes with it is inherited from the ",[52,8018,8019],{},"Also delete the local branch"," switch you last used when removing a session by hand, and only ever applies to a ",[22,8022,4800],{}," branch Plexus cut — see ",[99,8025,4725],{"href":3806},". Plexus only does this for a pull request it saw while it was open, and a message tells you afterwards what was removed.",[10,8028,8029,8030,132],{},"Configure all of these in ",[99,8031,102],{"href":101},[47,8033,8034],{"tone":69},[10,8035,4974,8036,8038,8039,8041,8042,8044,8045,8047],{},[52,8037,4910],{}," at its default of ",[52,8040,4936],{},", this runs a forced worktree removal in the background: a merge detected while the agent is mid-turn stops the agent and removes the worktree with anything uncommitted still in it, and there is no dialog to cancel. Set ",[52,8043,4910],{}," to ",[52,8046,4946],{}," if you want the automatic cleanup to keep everything on disk.",{"title":33,"searchDepth":266,"depth":266,"links":8049},[8050,8051,8055,8056,8057],{"id":7814,"depth":266,"text":7815},{"id":7831,"depth":266,"text":7832,"children":8052},[8053,8054],{"id":7858,"depth":271,"text":7859},{"id":7869,"depth":271,"text":7870},{"id":7880,"depth":266,"text":7881},{"id":7950,"depth":266,"text":7951},{"id":7982,"depth":266,"text":7983},"Open GitHub and Bitbucket pull requests and track their status from Plexus.","Github",{},26,{"title":2655,"description":8058},"docs\u002Fpull-requests","X4ASi98MIEKd4QtjTvlId3ml3-JYCUCCumKG-p_7x8A",{"id":8066,"title":4062,"body":8067,"description":8318,"extension":277,"group":5019,"icon":4213,"meta":8319,"navTitle":4062,"navigation":281,"order":8320,"path":1969,"seo":8321,"stem":8322,"__hash__":8323},"docs\u002Fdocs\u002Fterminal.md",{"type":7,"value":8068,"toc":8310},[8069,8074,8078,8083,8086,8097,8101,8104,8118,8124,8131,8134,8138,8157,8184,8187,8193,8262,8286,8290,8297,8300,8304],[10,8070,8071,8072,132],{},"Every session gets a bottom panel of plain shells rooted in its worktree — separate from the wrapped agent on the ",[99,8073,1431],{"href":1430},[14,8075,8077],{"id":8076},"open-and-close-the-panel","Open and close the panel",[10,8079,2067,8080,8082],{},[22,8081,1985],{}," from any tab to show or hide the bottom terminal panel. The first shell spawns automatically the moment the panel opens, as long as the session has a worktree.",[10,8084,8085],{},"Collapsing the panel hides the terminals but keeps their processes alive — a long-running build or watch keeps going while the panel is closed, and reopening re-attaches you to the full scrollback.",[47,8087,8088],{},[10,8089,8090,8092,8093,4176,8095,132],{},[22,8091,1996],{}," means Cmd on macOS and Ctrl on Windows\u002FLinux. Rebind the toggle under Keybindings in ",[99,8094,102],{"href":101},[99,8096,2000],{"href":1476},[14,8098,8100],{"id":8099},"run-multiple-shells","Run multiple shells",[10,8102,8103],{},"The panel is a tab strip, so you can keep several shells open at once:",[331,8105,8106,8111,8114],{},[334,8107,4123,8108,8110],{},[22,8109,1903],{}," to add a new terminal tab.",[334,8112,8113],{},"Click a tab's name to rename it inline.",[334,8115,4135,8116,4138],{},[22,8117,2423],{},[10,8119,8120],{},[1096,8121],{"alt":8122,"src":8123},"The terminal panel's tab strip with two shells open, the plus button to add another, and a close button on each tab.","\u002Fdocs\u002Fterminal.png",[10,8125,8126,8127,8130],{},"Each tab is an independent login shell with its own scrollback, started in the session's worktree directory. Use them to check ",[22,8128,8129],{},"git status",", run tests, tail logs, or poke at the codebase while the agent works on the Agent tab.",[10,8132,8133],{},"These shells belong to the session, not the agent. Stopping or tearing down a session kills its scratch shells; switching to another session leaves them running so nothing in flight is interrupted.",[14,8135,8137],{"id":8136},"copy-and-paste","Copy and paste",[10,8139,8140,8141,8143,8144,8146,8147,8150,8151,8153,8154,8156],{},"Select text with the mouse and copy it with ",[22,8142,5581],{},", then paste with ",[22,8145,5585],{},". This works in the scratch shells and in the wrapped ",[99,8148,8149],{"href":1430},"agent terminal",". In the agent terminal, ",[22,8152,5585],{}," also pastes an ",[52,8155,5609],{}," from the clipboard — a screenshot, say — straight into the prompt as an attachment.",[47,8158,8159],{},[10,8160,8161,8162,8164,8165,8167,8168,8171,8172,8175,8176,2639,8178,8180,8181,8183],{},"On Windows and Linux ",[22,8163,5581],{}," is ",[22,8166,5592],{},": it copies ",[52,8169,8170],{},"only when text is selected"," and otherwise sends the interrupt (",[22,8173,8174],{},"SIGINT",") to whatever is running — so one key keeps both behaviors. On macOS, ",[22,8177,5581],{},[22,8179,5585],{}," copy and paste while ",[22,8182,5592],{}," always interrupts.",[14,8185,4149],{"id":8186},"choose-which-shell-to-run",[10,8188,8189,8190,8192],{},"The shell Plexus spawns is controlled by ",[52,8191,4144],{}," (Settings → Advanced), a global setting that applies to your machine rather than per scope. The options depend on your platform:",[190,8194,8195,8203],{},[193,8196,8197],{},[196,8198,8199,8201],{},[199,8200,4924],{},[199,8202,4927],{},[209,8204,8205,8224,8249],{},[196,8206,8207,8213],{},[214,8208,8209,8212],{},[52,8210,8211],{},"Automatic"," (default)",[214,8214,8215,8216,8219,8220,8223],{},"Uses ",[22,8217,8218],{},"$SHELL"," on macOS\u002FLinux, or ",[22,8221,8222],{},"cmd.exe"," on Windows",[196,8225,8226,8229],{},[214,8227,8228],{},"Named platform shells",[214,8230,8231,8232,1432,8234,1432,8237,8240,8241,1432,8243,1432,8246],{},"macOS\u002FLinux: ",[22,8233,32],{},[22,8235,8236],{},"zsh",[22,8238,8239],{},"sh",". Windows: ",[22,8242,8222],{},[22,8244,8245],{},"powershell.exe",[22,8247,8248],{},"pwsh.exe",[196,8250,8251,8256],{},[214,8252,8253],{},[52,8254,8255],{},"Custom path…",[214,8257,8258,8259],{},"Runs the executable you point at with ",[52,8260,8261],{},"Custom shell path",[10,8263,8264,8265,8268,8269,8044,8271,8273,8274,8276,8277,853,8280,8283,8284,132],{},"To use a shell that isn't listed — ",[22,8266,8267],{},"fish",", say, or Git Bash on Windows — set ",[52,8270,4144],{},[52,8272,8255],{}," and put the full path in ",[52,8275,8261],{},", such as ",[22,8278,8279],{},"\u002Fusr\u002Fbin\u002Ffish",[22,8281,8282],{},"C:\\Program Files\\Git\\bin\\bash.exe",". Both live under Settings → Advanced — see ",[99,8285,102],{"href":101},[14,8287,8289],{"id":8288},"drag-files-in-from-your-os","Drag files in from your OS",[10,8291,8292,8293,8296],{},"Drag a file or folder from your file manager (Finder, Explorer, Nautilus, and the like) and drop it onto any terminal. Plexus inserts the absolute path at the cursor, shell-quoted only when it needs to be — a plain name stays bare, while a path with spaces or special characters is single-quoted. No newline is added, so you can build up a command (for example ",[22,8294,8295],{},"cat "," then drop a file) before pressing Enter. A highlight ring shows which terminal will receive the drop.",[10,8298,8299],{},"This works on the agent terminal too, not just scratch shells.",[14,8301,8303],{"id":8302},"theme","Theme",[10,8305,8306,8307,8309],{},"Open terminals follow the app theme. Switch between light and dark mode in ",[99,8308,1911],{"href":1910}," and every shell re-colors in place — no reload, no lost scrollback.",{"title":33,"searchDepth":266,"depth":266,"links":8311},[8312,8313,8314,8315,8316,8317],{"id":8076,"depth":266,"text":8077},{"id":8099,"depth":266,"text":8100},{"id":8136,"depth":266,"text":8137},{"id":8186,"depth":266,"text":4149},{"id":8288,"depth":266,"text":8289},{"id":8302,"depth":266,"text":8303},"A free shell in the worktree, open from any tab.",{},27,{"title":4062,"description":8318},"docs\u002Fterminal","UDIj9f4uDpGWMR2DvSLCiaWUlBdruhDRu-hMsVM4Trk",{"id":8325,"title":8326,"body":8327,"description":9045,"extension":277,"group":9046,"icon":9047,"meta":9048,"navTitle":389,"navigation":281,"order":9049,"path":388,"seo":9050,"stem":9051,"__hash__":9052},"docs\u002Fdocs\u002Fhooks.md","Lifecycle hooks",{"type":7,"value":8328,"toc":9032},[8329,8332,8336,8347,8406,8428,8432,8435,8464,8471,8475,8482,8535,8542,8546,8553,8575,8586,8592,8596,8609,8651,8655,8661,8735,8738,8744,8765,8768,8782,8790,8804,8846,8860,8866,8872,8894,8904,8908,8917,8921,8938,8958,8964,8968,8997,9004,9013,9015],[10,8330,8331],{},"Hooks are your own shell scripts that Plexus runs at key moments in a session's life, so every new worktree starts ready to work.",[14,8333,8335],{"id":8334},"the-three-events","The three events",[10,8337,8338,8339,8342,8343,8346],{},"A hook is attached to one lifecycle event. Each hook has a name and a multi-line command, run through ",[22,8340,8341],{},"sh -c"," on macOS and Linux or ",[22,8344,8345],{},"cmd.exe \u002FC"," on Windows — write it as a small script, not just a single line.",[190,8348,8349,8362],{},[193,8350,8351],{},[196,8352,8353,8356,8359],{},[199,8354,8355],{},"Event",[199,8357,8358],{},"When it fires",[199,8360,8361],{},"Typical use",[209,8363,8364,8380,8393],{},[196,8365,8366,8370,8377],{},[214,8367,8368],{},[52,8369,4249],{},[214,8371,8372,8373,8376],{},"A new session worktree is created — on a new branch or an ",[99,8374,8375],{"href":1269},"existing one"," alike",[214,8378,8379],{},"Install dependencies, scaffold local config, warm caches",[196,8381,8382,8387,8390],{},[214,8383,8384],{},[52,8385,8386],{},"Run",[214,8388,8389],{},"The agent starts or resumes",[214,8391,8392],{},"Start a dev server, tail a log, kick off a watcher",[196,8394,8395,8400,8403],{},[214,8396,8397],{},[52,8398,8399],{},"Teardown",[214,8401,8402],{},"A session is torn down",[214,8404,8405],{},"Stop background processes, clean up scratch resources",[47,8407,8408],{"tone":69},[10,8409,8410,8411,8413,8414,8417,8418,8420,8421,1432,8424,8427],{},"Hooks run on your machine with your permissions, your full ",[22,8412,44],{},", and your toolchain. A repository's committed hooks run ",[52,8415,8416],{},"in addition to"," the ones you set up in Plexus, so adding a repo as a project is enough for its scripts to run — leave ",[52,8419,4897],{}," on only for repos you trust. Plexus strips Anthropic credentials (",[22,8422,8423],{},"ANTHROPIC_API_KEY",[22,8425,8426],{},"ANTHROPIC_AUTH_TOKEN",") from a hook's environment, but everything else is reachable.",[14,8429,8431],{"id":8430},"where-hooks-are-defined","Where hooks are defined",[10,8433,8434],{},"Hooks live at three levels, and lower levels inherit from higher ones:",[331,8436,8437,8443,8448],{},[334,8438,8439,8442],{},[52,8440,8441],{},"Global"," — apply to every workspace, project, and session.",[334,8444,8445,8447],{},[52,8446,1537],{}," — apply to every project in that workspace.",[334,8449,8450,8452,8453,8456,8457,8459,8460,132],{},[52,8451,304],{}," — apply to every session in that project. This level has ",[52,8454,8455],{},"two sources",": the hooks you set up in Plexus, and the ones the repository commits to ",[22,8458,4893],{},". Both run — see ",[99,8461,8463],{"href":8462},"#repo-committed-hooks","Repo-committed hooks",[10,8465,8466,8467,8470],{},"Sessions never define their own hooks; they always inherit the composed plan from their project. To change what a session runs, edit its project-level hooks. Open ",[52,8468,8469],{},"Settings → Worktrees & Hooks",", pick a scope, then pick the Create \u002F Run \u002F Teardown event tab to edit that combination.",[14,8472,8474],{"id":8473},"composition-modes","Composition modes",[10,8476,8477,8478,8481],{},"A non-global level doesn't just add its hooks to the inherited ones — it declares a ",[52,8479,8480],{},"combine mode"," that says how its hooks join what it inherits.",[190,8483,8484,8493],{},[193,8485,8486],{},[196,8487,8488,8490],{},[199,8489,2222],{},[199,8491,8492],{},"Effect",[209,8494,8495,8505,8515,8525],{},[196,8496,8497,8502],{},[214,8498,8499],{},[52,8500,8501],{},"Override",[214,8503,8504],{},"Discard all inherited hooks; only this level's hooks run (the managed built-ins still run — see below).",[196,8506,8507,8512],{},[214,8508,8509],{},[52,8510,8511],{},"Before",[214,8513,8514],{},"Run this level's hooks ahead of the inherited ones.",[196,8516,8517,8522],{},[214,8518,8519,8212],{},[52,8520,8521],{},"After",[214,8523,8524],{},"Run this level's hooks behind the inherited ones.",[196,8526,8527,8532],{},[214,8528,8529],{},[52,8530,8531],{},"Parallel",[214,8533,8534],{},"Run this level's hooks concurrently, alongside the rest.",[10,8536,8537,8538,8541],{},"Set the mode from the ",[52,8539,8540],{},"Combine mode"," dropdown on each event tab at the workspace or project scope.",[14,8543,8545],{"id":8544},"resolution-and-execution-order","Resolution and execution order",[10,8547,8548,8549,8552],{},"Plexus resolves the plan top-down — ",[52,8550,8551],{},"global → workspace → project"," — applying each level's combine mode. At the project level, the repository's committed hooks and your app-managed project hooks are first joined into one ordered list (the repository's first, by default); that combined list is what the project's combine mode then applies. The resulting plan then runs in four phases, always in this order:",[1114,8554,8555,8560,8565,8570],{},[334,8556,8557,8559],{},[52,8558,8511],{}," — sequential. A non-zero exit can abort the launch (see below).",[334,8561,8562,8564],{},[52,8563,4740],{}," — the event's managed built-ins (for Create, the copy-paths step, and the port-file step when you've asked for one).",[334,8566,8567,8569],{},[52,8568,8531],{}," — concurrent, best-effort. A failure here never aborts.",[334,8571,8572,8574],{},[52,8573,8521],{}," — sequential, and always runs.",[10,8576,8577,8578,8581,8582,8585],{},"Within the ",[52,8579,8580],{},"Hooks defined here"," list, use the up\u002Fdown controls to set the order of your own hooks at that level. The live ",[52,8583,8584],{},"Resolved plan"," preview shows the final four-phase plan exactly as it will run — every hook, its source badge (Global \u002F Workspace \u002F Project \u002F Built-in \u002F From repo), and whether it's enabled. This is the fastest way to confirm inheritance did what you expect. Toggle any hook off without deleting it; disabled hooks stay in the list and appear dimmed in the preview.",[10,8587,8588],{},[1096,8589],{"alt":8590,"src":8591},"The Hooks settings panel: the Create \u002F Run \u002F Teardown event tabs, the global Hooks defined here list with reorder, toggle, edit, and delete controls, the New hook form, and the live Resolved plan preview showing the Before and Action phases.","\u002Fdocs\u002Fhooks.png",[14,8593,8595],{"id":8594},"the-managed-built-ins","The managed built-ins",[10,8597,8598,8599,8601,8602,8604,8605,8608],{},"On the ",[52,8600,4249],{}," event, Plexus runs up to two managed steps of its own. They live in the ",[52,8603,4740],{}," phase and are ",[52,8606,8607],{},"immune to Override",": even a project that overrides every inherited hook still gets them.",[331,8610,8611,8636],{},[334,8612,8613,8616,8617,8619,8620,1055,8623,8626,8627,1432,8629,8632,8633,8635],{},[52,8614,8615],{},"copy-paths"," copies configured files into the new worktree — this is how gitignored files like ",[22,8618,1458],{}," reach the session. Configure it with ",[52,8621,8622],{},"Copy files into new session folders",[52,8624,8625],{},"Files and folders to copy"," (default ",[22,8628,1458],{},[22,8630,8631],{},".env.local",") — see ",[99,8634,1463],{"href":1462}," for the full path rules.",[334,8637,8638,8641,8642,8646,8647,8650],{},[52,8639,8640],{},"port-env-file"," writes the session's ",[99,8643,8645],{"href":8644},"\u002Fdocs\u002Fworktrees#dev-server-ports","dev server ports"," into a file in the worktree. It only appears in the plan once ",[52,8648,8649],{},"Write ports to file"," names one; the setting is empty by default, so most plans never show this step. Unlike copy-paths it also runs again whenever the session is resumed, so the file always carries the ports the session is actually holding.",[14,8652,8654],{"id":8653},"what-a-hook-gets-in-its-environment","What a hook gets in its environment",[10,8656,8657,8658,8660],{},"Hooks inherit the environment Plexus itself was launched with — your ",[22,8659,44],{},", your toolchain, your shell's variables — minus the Anthropic credentials, which are always stripped. On top of that, a hook running for a session with a reserved port block gets:",[190,8662,8663,8673],{},[193,8664,8665],{},[196,8666,8667,8670],{},[199,8668,8669],{},"Variable",[199,8671,8672],{},"Value",[209,8674,8675,8685,8695,8708,8722],{},[196,8676,8677,8682],{},[214,8678,8679],{},[22,8680,8681],{},"PLEXUS_PORT",[214,8683,8684],{},"The session's first dev server port",[196,8686,8687,8692],{},[214,8688,8689],{},[22,8690,8691],{},"PLEXUS_PORT_BASE",[214,8693,8694],{},"The same number, for scripts that do arithmetic on it",[196,8696,8697,8702],{},[214,8698,8699],{},[22,8700,8701],{},"PLEXUS_PORT_COUNT",[214,8703,8704,8705,1912],{},"How many ports the block holds (",[22,8706,8707],{},"10",[196,8709,8710,8719],{},[214,8711,8712,8715,8716],{},[22,8713,8714],{},"PLEXUS_PORT_1"," … ",[22,8717,8718],{},"PLEXUS_PORT_9",[214,8720,8721],{},"The rest of the block",[196,8723,8724,8729],{},[214,8725,8726],{},[22,8727,8728],{},"PORT",[214,8730,8731,8732],{},"The first port again — this one is configurable, via ",[52,8733,8734],{},"Extra port variables",[10,8736,8737],{},"The same set reaches the agent and the session's terminal tab, so a server a hook starts and a command the agent runs by hand agree about which port to use.",[27,8739,8742],{"className":8740,"code":8741,"language":32,"meta":33},[30],"pnpm dev --port $PLEXUS_PORT\n",[22,8743,8741],{"__ignoreMap":33},[47,8745,8746],{},[10,8747,8748,8749,8752,8753,8756,8757,8760,8761,8764],{},"Treat these as ",[52,8750,8751],{},"optional",". They are absent for a session that holds no reservation — ",[52,8754,8755],{},"Assign dev server ports"," switched off, or a range with nothing free left in it — and a hook that hard-fails on an empty ",[22,8758,8759],{},"$PLEXUS_PORT"," would then stop a session from starting. See ",[99,8762,8763],{"href":8644},"Dev server ports"," for what is and isn't guaranteed.",[14,8766,8463],{"id":8767},"repo-committed-hooks",[10,8769,8770,8771,8773,8774,8777,8778,8781],{},"A team can share hooks by committing them to the repo at ",[22,8772,4893],{},". The file maps each event to an ordered array of ",[22,8775,8776],{},"{ name, command }"," entries; ",[22,8779,8780],{},"command"," may be multi-line and may call a repo script.",[27,8783,8788],{"className":8784,"code":8786,"language":8787,"meta":33},[8785],"language-json","{\n  \"create\": [\n    { \"name\": \"Install deps\", \"command\": \"pnpm install\" },\n    { \"name\": \"Setup\", \"command\": \"set -e\\nbash .plexus\u002Fhooks\u002Fsetup.sh\" }\n  ],\n  \"run\": [],\n  \"teardown\": []\n}\n","json",[22,8789,8786],{"__ignoreMap":33},[10,8791,8792,8793,8795,8796,8799,8800,8803],{},"When this manifest is present and ",[52,8794,4897],{}," (default on) is on, its hooks run ",[52,8797,8798],{},"alongside"," the project hooks you set up in Plexus. Cloning the repo is enough for a teammate to get the team's setup, and it no longer costs them the hooks they added for themselves. ",[52,8801,8802],{},"How repository hooks combine with yours"," (Settings → Worktrees & Hooks) decides which set goes first:",[190,8805,8806,8814],{},[193,8807,8808],{},[196,8809,8810,8812],{},[199,8811,8672],{},[199,8813,8492],{},[209,8815,8816,8826,8836],{},[196,8817,8818,8823],{},[214,8819,8820,8212],{},[52,8821,8822],{},"Repository hooks first, then your app-managed hooks",[214,8824,8825],{},"The committed hooks run, then yours.",[196,8827,8828,8833],{},[214,8829,8830],{},[52,8831,8832],{},"Your app-managed hooks first, then the repository's",[214,8834,8835],{},"Your hooks run first, then the committed ones.",[196,8837,8838,8843],{},[214,8839,8840],{},[52,8841,8842],{},"Repository hooks only (skip this project's app-managed hooks)",[214,8844,8845],{},"The committed hooks replace this project's app-managed hooks.",[10,8847,8848,8849,8851,8852,8855,8856,8859],{},"Both sets belong to the ",[52,8850,1602],{}," level, so they share that level's combine mode and run in the same phase. Your global and workspace hooks still run — ",[52,8853,8854],{},"unless this project's Combine mode is Override",", which discards inherited hooks whichever value you pick. The order has no effect ",[52,8857,8858],{},"under Parallel"," either, where the project level's hooks run concurrently.",[10,8861,8862,8863,8865],{},"Like the other hook settings, it layers ",[52,8864,1593],{},": one global choice covers every project, and a single project can still differ.",[10,8867,8868,8869,8871],{},"Plexus shows a \"Repo hooks active\" banner with the ",[52,8870,4897],{}," toggle on the Project scope; turn it off to run only your own hooks, without deleting the file. If the manifest fails to parse, the error is surfaced in the editor and only your app-managed project hooks run, rather than breaking the session.",[47,8873,8874],{},[10,8875,8876,8879,8880,8882,8883,8886,8887,8889,8890,8893],{},[52,8877,8878],{},"If you used repository hooks before this version:"," a committed ",[22,8881,4893],{}," used to ",[91,8884,8885],{},"replace"," that project's app-managed hooks — every event, even the ones the file says nothing about. Both sets run now, so hooks you set up in Plexus for such a project start running again the next time a session starts, resumes, or is torn down — including the teardown that runs when you delete a session or project, which happens without a session start. Open ",[52,8888,8469],{}," on the project to see exactly what will run (the editor points this out once, on projects that have both), and pick ",[52,8891,8892],{},"Repository hooks only"," if you want the old behavior back.",[47,8895,8896],{"tone":69},[10,8897,8898,8900,8901,8903],{},[52,8899,8892],{}," is the one value that silences your own project hooks, and it follows the file. If a later commit empties ",[22,8902,4893],{}," — the file is still there, but declares nothing for an event — this project contributes nothing of its own to that event. The hooks you set up in Plexus don't come back to fill the gap.",[14,8905,8907],{"id":8906},"aborting-on-failure","Aborting on failure",[10,8909,8910,8913,8914,8916],{},[52,8911,8912],{},"Stop if a setup step fails"," (Settings → Worktrees & Hooks, default on) stops a session launch if a ",[52,8915,4249],{}," hook in the before or action phase exits non-zero — so you never get a half-set-up worktree. Run and teardown hooks never abort the lifecycle. Override the setting to make Create hooks non-blocking. Repository hooks and the ones you set up in Plexus are treated identically here — a non-zero exit from either aborts a Create the same way.",[14,8918,8920],{"id":8919},"hook-timeout","Hook timeout",[10,8922,8923,8925,8926,8929,8930,3456,8933,8937],{},[52,8924,8920],{}," (Settings → Worktrees & Hooks, default ",[52,8927,8928],{},"600 seconds",", set globally or per project) caps how long any single hook command may run. On expiry the command and everything it started are stopped, and the hook is recorded as ",[52,8931,8932],{},"timed out",[99,8934,8936],{"href":8935},"#viewing-hook-output","Hook output"," tab.",[10,8939,8940,8941,8943,8944,8946,8947,8950,8951,8954,8955,8957],{},"A timeout is deliberately ",[52,8942,168],{}," treated as the hook failing: it never stops a launch, even with ",[91,8945,8912],{}," on. Stopping there would delete the session's working copy — and, when Plexus cut it, its branch — over something transient, and a cold ",[22,8948,8949],{},"pnpm install"," or a first checkout of a large repository really can outrun ten minutes. So the session starts, whatever the hook managed to do is left in place, and the tab tells you which step was cut short. Rerun it yourself, or raise the timeout and start again. A hook that exits with an ",[91,8952,8953],{},"error"," still stops the launch as before — that's the hook saying no, rather than Plexus giving up waiting. Either way, a session started on an ",[99,8956,6256],{"href":1269}," loses only its half-built worktree: the branch itself is never removed by an abort.",[10,8959,8960,8961,8963],{},"Raise the timeout if you have a legitimately long setup step. There is no \"unlimited\" option on purpose: a hook that leaves a background process running would otherwise hold the session's launch open indefinitely. If a hook is simply taking too long right now, ",[52,8962,1186],{}," on the starting session stops it.",[14,8965,8967],{"id":8966},"viewing-hook-output","Viewing hook output",[10,8969,8970,8971,8973,8974,8977,8978,8980,8981,1055,8983,8985,8986,1432,8989,8992,8993,8996],{},"Open a session's ",[52,8972,8936],{}," tab — on the right of the session tab row, set apart from Agent, Review, Explorer, and Git, with the session's ",[52,8975,8976],{},"Open localhost"," button beside it when it holds a block of ",[99,8979,8645],{"href":8644}," — to see what its hooks actually did. Each ",[52,8982,4249],{},[52,8984,8386],{}," hook is listed with its captured ",[22,8987,8988],{},"stdout",[22,8990,8991],{},"stderr",", and exit status; a hook that exited non-zero (or that aborted the launch) is flagged in red, and a hook that printed nothing shows ",[22,8994,8995],{},"(no output)",". This is where a hook that prints something meaningful surfaces it, and the first place to look when a launch fails.",[10,8998,8999,9000,9003],{},"Plexus keeps the ",[52,9001,9002],{},"latest run of each event",": Run hooks re-run on every start and resume, so the tab always reflects the most recent launch; Create hooks run once when the worktree is made, and their output is kept even if the create hook fails and the launch rolls back — so you can reopen a failed session and see exactly why. The output persists across app restarts.",[47,9005,9006],{"tone":69},[10,9007,9008,9009,9012],{},"Hook output is stored locally in Plexus's database so it survives restarts. If a hook prints secrets (for example running ",[22,9010,9011],{},"env"," or echoing a token), that text is written to disk. Each stream is capped at 64 KB.",[14,9014,2343],{"id":2342},[331,9016,9017,9022,9027],{},[334,9018,9019,9021],{},[99,9020,1463],{"href":1462}," — the copy-paths built-in, the environment-file rules, and the dev server ports a hook can read.",[334,9023,9024,9026],{},[99,9025,1856],{"href":1855}," — how Plexus stores credentials in the OS keystore.",[334,9028,9029,9031],{},[99,9030,102],{"href":101}," — every hooks and worktree setting and its default.",{"title":33,"searchDepth":266,"depth":266,"links":9033},[9034,9035,9036,9037,9038,9039,9040,9041,9042,9043,9044],{"id":8334,"depth":266,"text":8335},{"id":8430,"depth":266,"text":8431},{"id":8473,"depth":266,"text":8474},{"id":8544,"depth":266,"text":8545},{"id":8594,"depth":266,"text":8595},{"id":8653,"depth":266,"text":8654},{"id":8767,"depth":266,"text":8463},{"id":8906,"depth":266,"text":8907},{"id":8919,"depth":266,"text":8920},{"id":8966,"depth":266,"text":8967},{"id":2342,"depth":266,"text":2343},"Run your own scripts on session create, run, and teardown.","Automation","RefreshCw",{},30,{"title":8326,"description":9045},"docs\u002Fhooks","IqWk_zlANrqu11jTmmIjtmRXYBOS4YBSLGjt4Wq6BqE",{"id":9054,"title":9055,"body":9056,"description":9773,"extension":277,"group":9046,"icon":9774,"meta":9775,"navTitle":9776,"navigation":281,"order":9777,"path":1462,"seo":9778,"stem":9779,"__hash__":9780},"docs\u002Fdocs\u002Fworktrees.md","Worktrees & env files",{"type":7,"value":9057,"toc":9754},[9058,9061,9065,9071,9077,9093,9097,9107,9111,9120,9131,9135,9146,9151,9155,9158,9199,9207,9211,9228,9234,9245,9249,9252,9275,9278,9289,9292,9316,9320,9380,9419,9437,9441,9447,9452,9462,9470,9476,9497,9501,9508,9525,9535,9539,9557,9567,9576,9619,9629,9644,9649,9652,9657,9663,9667,9689,9692,9698,9706,9732,9734],[10,9059,9060],{},"Every off-main session runs in its own git worktree. Plexus copies the env files it needs in as the worktree is created, and gives it its own block of dev server ports.",[14,9062,9064],{"id":9063},"where-worktrees-live","Where worktrees live",[10,9066,9067,9068,9070],{},"When you start a session, Plexus cuts a git worktree for it — on a new branch off the base you picked, or on the ",[99,9069,6256],{"href":1269}," you chose. By default it lands at:",[27,9072,9075],{"className":9073,"code":9074,"language":485},[483],"\u003Cproject>\u002Fworktrees\u002F\u003Csession-name>\n",[22,9076,9074],{"__ignoreMap":33},[10,9078,9079,9080,8925,9083,9086,9087,9089,9090,9092],{},"The subfolder comes from ",[52,9081,9082],{},"Where to create session folders",[22,9084,9085],{},"worktrees","); the session name is slugified and appended automatically. The value is always a relative path under the project root — it can never escape it. The layout, the env-file copying below, and the ",[99,9088,4280],{"href":388}," are the same whichever way the session got its branch. Root-tree sessions don't get a worktree; they run directly in the project's root working tree. See ",[99,9091,312],{"href":1293}," for the full lifecycle.",[105,9094,9096],{"id":9095},"auto-gitignore","Auto-gitignore",[10,9098,9099,9100,9102,9103,9106],{},"When a worktree is created inside the repo, Plexus adds its parent folder to the repo's ",[22,9101,3440],{}," so worktree contents never surface as untracked changes. This is ",[52,9104,9105],{},"Hide session folders from git"," (Settings → Worktrees & Hooks, default on). Leave it on unless you're managing the ignore entry yourself.",[14,9108,9110],{"id":9109},"cleaning-up-worktrees","Cleaning up worktrees",[10,9112,9113,9114,9116,9117,9119],{},"Removing a session tears its worktree down: the folder goes, and so does git's own record of it. Archiving keeps both, so the session stays resumable. Removing a whole ",[99,9115,1602],{"href":2058}," or workspace offers the same choice — a ",[52,9118,4858],{}," switch in the confirmation, off by default, so nothing with uncommitted work in it disappears unless you say so.",[10,9121,9122,9123,9125,9126,9128,9129,132],{},"Leftovers can still happen: you delete a worktree folder yourself, a drive goes away mid-teardown, or you chose to keep the worktrees when removing a project. Those are cleaned up from the Git tab's ",[52,9124,1463],{}," section — see ",[99,9127,2878],{"href":4411},", which also covers why a leftover keeps git from letting you delete or check out that branch. Tearing a worktree down never takes a branch Plexus didn't create with it — see ",[99,9130,4725],{"href":3806},[14,9132,9134],{"id":9133},"why-env-files-need-copying","Why env files need copying",[10,9136,9137,9138,1055,9140,9142,9143,9145],{},"A fresh worktree is a clean checkout — it holds only tracked files. Anything gitignored, most importantly ",[22,9139,1458],{},[22,9141,8631],{},", is ",[52,9144,168],{}," carried over. A dev server or test runner that reads those files would break the moment the agent runs it inside the worktree.",[10,9147,9148,9149,132],{},"So as each worktree is created, Plexus copies the paths you configure into it — regardless of ",[22,9150,3440],{},[14,9152,9154],{"id":9153},"copying-paths-into-worktrees","Copying paths into worktrees",[10,9156,9157],{},"Two settings control the copy:",[190,9159,9160,9170],{},[193,9161,9162],{},[196,9163,9164,9166,9168],{},[199,9165,5636],{},[199,9167,1067],{},[199,9169,4743],{},[209,9171,9172,9184],{},[196,9173,9174,9178,9181],{},[214,9175,9176],{},[52,9177,8622],{},[214,9179,9180],{},"On",[214,9182,9183],{},"Whether to copy any paths into a new worktree",[196,9185,9186,9190,9196],{},[214,9187,9188],{},[52,9189,8625],{},[214,9191,9192,1432,9194],{},[22,9193,1458],{},[22,9195,8631],{},[214,9197,9198],{},"The files and folders to copy",[10,9200,9201,9202,1055,9204,9206],{},"Out of the box, ",[22,9203,1458],{},[22,9205,8631],{}," land in every new session worktree.",[105,9208,9210],{"id":9209},"adding-paths","Adding paths",[1114,9212,9213,9219,9225],{},[334,9214,9215,9216,9218],{},"Open ",[99,9217,102],{"href":101}," and go to the Worktrees & Hooks page.",[334,9220,9221,9222,9224],{},"Make sure ",[52,9223,8622],{}," is on.",[334,9226,9227],{},"Add each file or folder you want copied to the paths list, using the add\u002Fremove controls.",[10,9229,9230],{},[1096,9231],{"alt":9232,"src":9233},"The Worktrees settings panel: the worktree folder field, the auto-gitignore and copy-into-new-worktrees toggles, and the paths-to-copy list with .env, .env.local, vendor\u002F, and node_modules entries plus add and remove controls.","\u002Fdocs\u002Fworktrees.png",[10,9235,9236,9237,9240,9241,9244],{},"Paths are relative to the project root and copied as-is whether or not git tracks them; folders are copied recursively. Common additions are ",[22,9238,9239],{},".env.development",", a local ",[22,9242,9243],{},"config\u002F"," folder, or service-account credentials that live outside version control. Like any setting, these layer per scope — set a baseline globally and override it for one project.",[105,9246,9248],{"id":9247},"path-safety","Path safety",[10,9250,9251],{},"Plexus validates every copy path so a worktree can't be corrupted or used to escape the repo:",[331,9253,9254,9261,9266,9269],{},[334,9255,9256,9257,9260],{},"Absolute paths and ",[22,9258,9259],{},".."," traversal are rejected.",[334,9262,9263,9265],{},[22,9264,132],{}," and empty entries are rejected.",[334,9267,9268],{},"Symlinks are skipped — a top-level symlink copies nothing, and symlinks inside a copied folder are skipped — so the copy can't leak files from outside the repo.",[334,9270,9271,9272,9274],{},"Missing sources are silently skipped, so a path that doesn't exist in a given project won't fail the launch. A path that disappears mid-copy — e.g. a tool rewriting ",[22,9273,1458],{}," at that instant — is skipped the same way rather than failing the launch. A genuine error (an unreadable file, a full disk) still stops the launch, but the message names the exact path so you know what to fix.",[14,9276,8763],{"id":9277},"dev-server-ports",[10,9279,9280,9281,9284,9285,9288],{},"Two sessions of the same repository both want to run the dev server, and a hardcoded ",[22,9282,9283],{},":3000"," somewhere in the project means the second one fails to bind. So Plexus gives ",[52,9286,9287],{},"every session its own block of 10 localhost ports"," and puts them in the environment of everything it starts for that session.",[10,9290,9291],{},"The block is reserved when the session starts. Plexus checks the whole block is actually free before it commits to it, and the session keeps it for as long as its working copy exists — resuming a session hands back the same ports it had, so a dev server left running isn't moved out from under itself. Tearing the worktree down releases the block for the next session.",[10,9293,9294,9295,9298,9299,9301,9302,1055,9305,9308,9309,9311,9312,9315],{},"A session holding a block says so in two places. Open the session and its tab strip carries an ",[52,9296,9297],{},"Open localhost:20030"," button, beside ",[52,9300,8936],{}," — one click opens your browser at that port, and the caret next to it holds ",[52,9303,9304],{},"Copy port",[52,9306,9307],{},"Reassign ports",". On the ",[99,9310,1679],{"href":1357},", which has no session tab strip and is where you compare one session's ports against another's, each row shows its first port as a small chip instead; hover it and the tooltip names the whole range, ",[22,9313,9314],{},"Ports 20030–20039",". A session with no block shows neither.",[105,9317,9319],{"id":9318},"the-variables","The variables",[190,9321,9322,9330],{},[193,9323,9324],{},[196,9325,9326,9328],{},[199,9327,8669],{},[199,9329,8672],{},[209,9331,9332,9341,9350,9360,9371],{},[196,9333,9334,9338],{},[214,9335,9336],{},[22,9337,8681],{},[214,9339,9340],{},"The session's first port — the one to use",[196,9342,9343,9347],{},[214,9344,9345],{},[22,9346,8691],{},[214,9348,9349],{},"The same number, spelled out for scripts that do arithmetic on it",[196,9351,9352,9356],{},[214,9353,9354],{},[22,9355,8701],{},[214,9357,8704,9358,1912],{},[22,9359,8707],{},[196,9361,9362,9368],{},[214,9363,9364,8715,9366],{},[22,9365,8714],{},[22,9367,8718],{},[214,9369,9370],{},"The rest of the block — a second server, a test database, a debugger port",[196,9372,9373,9377],{},[214,9374,9375],{},[22,9376,8728],{},[214,9378,9379],{},"The first port again, under the name most runtimes already read",[10,9381,9382,9383,9385,9386,9388,9389,1432,9392,1432,9395,9398,9399,9402,9403,9406,9407,1432,9409,1432,9412,1432,9415,9418],{},"That last one comes from ",[52,9384,8734],{}," (Settings → Worktrees & Hooks), which starts out as ",[22,9387,8728],{}," and takes any names you want — ",[22,9390,9391],{},"VITE_PORT",[22,9393,9394],{},"API_PORT",[22,9396,9397],{},"RAILS_PORT",". Each one is set to the session's ",[52,9400,9401],{},"first"," port. Names beginning with ",[22,9404,9405],{},"PLEXUS_"," are refused, as are the ones the toolchain depends on (",[22,9408,44],{},[22,9410,9411],{},"HOME",[22,9413,9414],{},"SHELL",[22,9416,9417],{},"TERM",", and the Anthropic credentials).",[10,9420,9421,9422,9425,9426,9428,9429,9432,9433,9436],{},"The variables reach the session's ",[52,9423,9424],{},"agent",", the session's ",[52,9427,1970],{}," tab, and every ",[99,9430,9431],{"href":388},"lifecycle hook",". The project view's own Terminal tab gets ",[52,9434,9435],{},"no"," port variables: it runs in the project's main checkout, which belongs to no session, so handing it one session's block would aim it at ports another worktree is already using.",[105,9438,9440],{"id":9439},"starting-a-server-on-them","Starting a server on them",[10,9442,9443,9444,9446],{},"The intended home is a ",[52,9445,4625],{}," hook, which fires every time the agent starts or resumes:",[27,9448,9450],{"className":9449,"code":8741,"language":32,"meta":33},[30],[22,9451,8741],{"__ignoreMap":33},[10,9453,9454,9455,9457,9458,9461],{},"On Windows a hook runs through ",[22,9456,8222],{},", so write ",[22,9459,9460],{},"%PLEXUS_PORT%"," there.",[10,9463,9464,9465,9467,9468,607],{},"Commit that to the repository's ",[22,9466,4893],{}," and everyone on the team gets it from a clone — see ",[99,9469,8463],{"href":4901},[27,9471,9474],{"className":9472,"code":9473,"language":8787,"meta":33},[8785],"{\n  \"run\": [\n    { \"name\": \"Dev server\", \"command\": \"pnpm dev --port $PLEXUS_PORT\" }\n  ]\n}\n",[22,9475,9473],{"__ignoreMap":33},[47,9477,9478],{"tone":69},[10,9479,9480,9483,9484,9486,9487,9492,9493,9496],{},[52,9481,9482],{},"Your dev server has to be told."," Plexus sets the variables; it does not detect your framework and it does not add flags to your commands. Next.js, Nuxt, Rails and Express read ",[22,9485,8728],{}," on their own and need nothing more. ",[52,9488,9489,9490],{},"Vite, Astro and Angular ignore ",[22,9491,8728],{}," — they need ",[22,9494,9495],{},"--port $PLEXUS_PORT"," on the command, or the value threaded into their config file. If nothing in your project reads these variables, nothing changes.",[105,9498,9500],{"id":9499},"the-range","The range",[10,9502,9503,9504,9507],{},"Blocks are handed out of ",[52,9505,9506],{},"20000–32000"," by default — around 1200 of them, far more than you will ever have sessions. That window is deliberate: it sits above every common dev-server port (3000, 4200, 5000, 5173, 8000, 8080), above 10080 (the highest port Chrome and Firefox refuse to open, which would give you a server that starts fine and a browser that won't load it), and below 32768, where Linux starts handing the same numbers to outgoing connections.",[10,9509,9510,9511,1055,9514,9517,9518,9520,9521,9524],{},"Move it with ",[52,9512,9513],{},"First port",[52,9515,9516],{},"Last port"," if it clashes with something on your machine. ",[52,9519,9516],{}," is an ",[91,9522,9523],{},"exclusive"," bound — a whole block of 10 has to fit below it, so the default of 32000 hands out ports up to 31999 — and a range too narrow to hold a single block is treated as a typo and ignored in favour of the defaults.",[10,9526,9527,9528,9531,9532,9534],{},"If every block in the range is taken or busy, the session ",[52,9529,9530],{},"still starts"," — it just gets no port variables, and a hook that reads ",[22,9533,8759],{}," sees an empty value. Write hooks that tolerate that.",[105,9536,9538],{"id":9537},"the-port-actions-on-a-session","The port actions on a session",[10,9540,9541,9542,9544,9545,9548,9549,1055,9551,9553,9554,132],{},"The button in the session's tab strip sits to the left of the ",[52,9543,8936],{}," tab and is split in two. Its main half opens ",[22,9546,9547],{},"http:\u002F\u002Flocalhost:\u003Cport>"," in your real browser; the caret beside it holds ",[52,9550,9304],{},[52,9552,9307],{},", so nothing about the session's ports needs you to leave the session. Hover it and the tooltip names the whole block — ",[22,9555,9556],{},"Open http:\u002F\u002Flocalhost:20030 — ports 20030–20039",[10,9558,9559,9560,4996,9563,9566],{},"The label shortens as space runs out: ",[22,9561,9562],{},"localhost:20030",[99,9564,9565],{"href":1910},"Compact",", and just the icon on a narrow pane, so the tabs beside it stay reachable however far you drag the sidebar over. The button keeps its full name for screen readers and voice control at every width.",[10,9568,9569,9570,9572,9573,9575],{},"The same three actions are on every session's ",[22,9571,1083],{}," menu — on its sidebar row and on its ",[99,9574,1679],{"href":1357}," row alike — in a group of their own:",[190,9577,9578,9586],{},[193,9579,9580],{},[196,9581,9582,9584],{},[199,9583,4740],{},[199,9585,4743],{},[209,9587,9588,9601,9610],{},[196,9589,9590,9595],{},[214,9591,9592],{},[52,9593,9594],{},"Open localhost:\u003Cport>",[214,9596,9597,9598,9600],{},"Opens ",[22,9599,9547],{}," in your real browser, at the session's first port",[196,9602,9603,9607],{},[214,9604,9605],{},[52,9606,9304],{},[214,9608,9609],{},"Copies that number to the clipboard",[196,9611,9612,9616],{},[214,9613,9614],{},[52,9615,9307],{},[214,9617,9618],{},"Drops the session's block and searches for another",[10,9620,9621,9622,9625,9626,9628],{},"Button and menu group alike are ",[52,9623,9624],{},"hidden",", not greyed out, for a session that holds no block. There is nothing you could do from either to make ports appear — only starting or resuming a session reserves its first block — so a disabled control would promise something it can't deliver. The button needs one thing more: ",[52,9627,8755],{}," on for that project. Switch that setting off and it goes at once, no restart needed, because with the feature off nothing was ever told which port to listen on.",[10,9630,9631,9633,9634,9636,9637,9639,9640,9643],{},[52,9632,8976],{}," — the button and the menu item alike — assumes your dev server is listening on the session's ",[91,9635,9401],{}," port. That's the convention ",[22,9638,8681],{}," sets up, but Plexus doesn't check: if your run hook points the server at ",[22,9641,9642],{},"$PLEXUS_PORT_1",", or the server isn't running, you'll get your browser's own error page.",[9645,9646,9648],"h4",{"id":9647},"reassigning","Reassigning",[10,9650,9651],{},"A reservation is remembered, not re-checked. That's deliberate — re-probing on resume could move a running server's ports out from under it — but it means that while a session is stopped, something else on your machine can take one of its ports, and the session comes back to a block it can no longer bind.",[10,9653,9654,9656],{},[52,9655,9307],{}," drops the current reservation and searches again. A session that has never started gets its first block from starting, not from here. If nothing has taken the old block after all, the search finds it free and hands it straight back — you asked for a block that works, not for a different number. If the search comes up empty, the session is left holding no block at all: a toast says so, the port button goes, and the session gets ports again the next time it starts or resumes.",[10,9658,9659,9662],{},[52,9660,9661],{},"Reassigning does not move a dev server that is already running."," The variables are handed to the things Plexus starts, at the moment it starts them, so a server a run hook launched keeps listening exactly where it was told to while the button and the menu already name the new block. Reassign while the session is stopped, or restart it afterwards, and the new numbers take effect.",[105,9664,9666],{"id":9665},"writing-the-ports-to-a-file","Writing the ports to a file",[10,9668,9669,9670,9672,9673,853,9675,9677,9678,9681,9682,9684,9685,9688],{},"Environment variables only reach what Plexus itself starts. ",[52,9671,8649],{}," (Settings → Worktrees & Hooks, empty by default) additionally maintains the same variables in a file inside the session's working copy — typically ",[22,9674,1458],{},[22,9676,8631],{}," — for the things that don't inherit an environment from Plexus: ",[22,9679,9680],{},"docker compose"," reading ",[22,9683,1458],{}," for ",[22,9686,9687],{},"${VAR}"," substitution, or a server you launch from your own terminal or IDE.",[10,9690,9691],{},"Plexus owns only the block between its two marker comments and leaves the rest of the file byte-for-byte alone:",[27,9693,9696],{"className":9694,"code":9695,"language":32,"meta":33},[30],"# >>> plexus ports >>>\nPLEXUS_PORT=20030\nPLEXUS_PORT_BASE=20030\nPLEXUS_PORT_COUNT=10\nPLEXUS_PORT_1=20031\nPLEXUS_PORT_2=20032\nPLEXUS_PORT_3=20033\nPLEXUS_PORT_4=20034\nPLEXUS_PORT_5=20035\nPLEXUS_PORT_6=20036\nPLEXUS_PORT_7=20037\nPLEXUS_PORT_8=20038\nPLEXUS_PORT_9=20039\nPORT=20030\n# \u003C\u003C\u003C plexus ports \u003C\u003C\u003C\n",[22,9697,9695],{"__ignoreMap":33},[10,9699,9700,9701,9705],{},"The block is written when the session's working copy is created and refreshed every time the session is resumed, so it always carries the ports the session is actually holding. The file is registered in the repository's local git excludes, so one machine's port numbers never end up in a commit an agent makes. Point the setting at a different file and the old one's block is cleaned up. Nothing is written for a ",[99,9702,9704],{"href":9703},"\u002Fdocs\u002Fsessions#start-session-on-root-tree","root-tree session"," — the \"worktree\" there is your own checkout.",[47,9707,9708],{"tone":69},[10,9709,9710,9713,9714,4996,9716,9718,9719,9721,9722,9724,9725,9728,9729,9731],{},[52,9711,9712],{},"A file is not a way to change a dev server's listen port."," Putting ",[22,9715,8728],{},[22,9717,1458],{}," works only for a runtime that reads ",[22,9720,8728],{}," out of the environment after loading that file — Vite, for one, loads ",[22,9723,8631],{}," but never takes ",[22,9726,9727],{},"server.port"," from it. Use the file for compose services, database ports and application config; use ",[22,9730,9495],{}," on the command for the dev server itself.",[14,9733,2343],{"id":2342},[331,9735,9736,9741,9749],{},[334,9737,9738,9740],{},[99,9739,389],{"href":388}," — run your own scripts at create, run, and teardown; the copy-paths step is a built-in that runs during create, and a run hook is where a dev server belongs.",[334,9742,9743,9745,9746,9748],{},[99,9744,1856],{"href":1855}," — keep API keys in your OS keystore instead of committing or copying them through ",[22,9747,1458],{}," files.",[334,9750,9751,9753],{},[99,9752,102],{"href":101}," — every worktree setting and its default.",{"title":33,"searchDepth":266,"depth":266,"links":9755},[9756,9759,9760,9761,9765,9772],{"id":9063,"depth":266,"text":9064,"children":9757},[9758],{"id":9095,"depth":271,"text":9096},{"id":9109,"depth":266,"text":9110},{"id":9133,"depth":266,"text":9134},{"id":9153,"depth":266,"text":9154,"children":9762},[9763,9764],{"id":9209,"depth":271,"text":9210},{"id":9247,"depth":271,"text":9248},{"id":9277,"depth":266,"text":8763,"children":9766},[9767,9768,9769,9770,9771],{"id":9318,"depth":271,"text":9319},{"id":9439,"depth":271,"text":9440},{"id":9499,"depth":271,"text":9500},{"id":9537,"depth":271,"text":9538},{"id":9665,"depth":271,"text":9666},{"id":2342,"depth":266,"text":2343},"Where session worktrees live, how to get .env files into them, and the dev server ports each session gets.","FolderGit2",{},"Worktrees & env",31,{"title":9055,"description":9773},"docs\u002Fworktrees","isGFz70GnoojOpO06S2YKDq84yr5XVctwx16jHfbqKY",{"id":9782,"title":1856,"body":9783,"description":9914,"extension":277,"group":9046,"icon":9915,"meta":9916,"navTitle":1856,"navigation":281,"order":9917,"path":1855,"seo":9918,"stem":9919,"__hash__":9920},"docs\u002Fdocs\u002Fsecrets.md",{"type":7,"value":9784,"toc":9908},[9785,9788,9792,9795,9830,9834,9849,9852,9856,9867,9875,9883,9891,9893],[10,9786,9787],{},"Plexus keeps sensitive values out of plaintext config by storing them in your operating system's keystore.",[14,9789,9791],{"id":9790},"where-secrets-live","Where secrets live",[10,9793,9794],{},"Secrets are written to the native credential store for your platform — never to Plexus's own config, database, or logs.",[190,9796,9797,9807],{},[193,9798,9799],{},[196,9800,9801,9804],{},[199,9802,9803],{},"Platform",[199,9805,9806],{},"Backing store",[209,9808,9809,9816,9823],{},[196,9810,9811,9813],{},[214,9812,216],{},[214,9814,9815],{},"Keychain",[196,9817,9818,9820],{},[214,9819,245],{},[214,9821,9822],{},"Credential Manager",[196,9824,9825,9827],{},[214,9826,227],{},[214,9828,9829],{},"Secret Service (freedesktop keyring)",[14,9831,9833],{"id":9832},"write-only-by-design","Write-only by design",[10,9835,9836,9837,9840,9841,9844,9845,9848],{},"Secrets support three operations: ",[52,9838,9839],{},"set"," a value, ",[52,9842,9843],{},"check"," whether one exists, and ",[52,9846,9847],{},"delete"," it. There is deliberately no read-back. Once a secret is stored, the interface can only confirm that a value is present or absent — it can never display, copy, or return it.",[10,9850,9851],{},"This is a security boundary, not a missing feature. Values stay inside the backend and the OS keystore; they never cross into the UI. To change a stored secret, set it again with a new value. To retire one, delete it.",[14,9853,9855],{"id":9854},"how-hooks-use-secrets","How hooks use secrets",[10,9857,9858,9859,9861,9862,9864,9865,502],{},"Your ",[99,9860,1589],{"href":388}," run as shell commands, so they read whatever they need from their own environment and from the worktree — including environment files brought in by the ",[52,9863,8625],{}," setting (see ",[99,9866,1270],{"href":1462},[10,9868,9869,9870,1055,9872,9874],{},"To protect your credentials, Plexus scrubs its own sensitive environment before spawning any hook child process. The Anthropic credentials Plexus uses to run Claude Code — ",[22,9871,8423],{},[22,9873,8426],{}," — are always stripped, even if a hook tries to set them itself. This is automatic and unconditional.",[10,9876,9877,9878,1432,9880,9882],{},"Hooks otherwise inherit a normal environment (your ",[22,9879,44],{},[22,9881,9411],{},", and toolchain), so they can run the tools they need without ever seeing your agent credentials.",[47,9884,9885],{"tone":69},[10,9886,9887,9888,9890],{},"Repo-committed hooks in ",[22,9889,4893],{}," run with the same shell access you have. Treat a project's hooks as code you are about to execute: review them before enabling repo hooks on a repository you don't trust.",[14,9892,2343],{"id":2342},[331,9894,9895,9900],{},[334,9896,9897,9899],{},[99,9898,389],{"href":388}," — what runs, when, and in what order",[334,9901,9902,9904,9905,9907],{},[99,9903,1270],{"href":1462}," — copy gitignored files like ",[22,9906,1458],{}," into each session",{"title":33,"searchDepth":266,"depth":266,"links":9909},[9910,9911,9912,9913],{"id":9790,"depth":266,"text":9791},{"id":9832,"depth":266,"text":9833},{"id":9854,"depth":266,"text":9855},{"id":2342,"depth":266,"text":2343},"Store secrets in your OS keychain for use by hooks.","KeyRound",{},32,{"title":1856,"description":9914},"docs\u002Fsecrets","yxsLgDxZULF8gaP298FiyWQObD8iiUaCjTZw_b5r_Cw",{"id":9922,"title":9923,"body":9924,"description":10291,"extension":277,"group":10292,"icon":10293,"meta":10294,"navTitle":10295,"navigation":281,"order":10296,"path":172,"seo":10297,"stem":10298,"__hash__":10299},"docs\u002Fdocs\u002Fconnections.md","Connecting a git provider",{"type":7,"value":9925,"toc":10283},[9926,9936,9940,9951,9962,9966,9979,9985,9988,10034,10045,10049,10059,10075,10086,10090,10108,10111,10117,10120,10150,10156,10168,10174,10185,10198,10217,10221,10228,10241,10259,10263,10274],[10,9927,9928,9929,1055,9932,9935],{},"Plexus opens and tracks pull requests directly on ",[52,9930,9931],{},"GitHub",[52,9933,9934],{},"Bitbucket",". Connecting a provider is a one-click sign-in — no CLI to install, no personal access tokens to paste.",[14,9937,9939],{"id":9938},"connect-a-provider","Connect a provider",[10,9941,9215,9942,157,9944,853,9947,9950],{},[52,9943,156],{},[52,9945,9946],{},"Connect GitHub",[52,9948,9949],{},"Connect Bitbucket",". Your browser opens the provider's normal authorization screen; approve it and you're returned to Plexus, connected. The status line shows the account you're signed in as.",[47,9952,9953],{},[10,9954,9955,9956,9959,9960,132],{},"Once a provider is connected you can also ",[52,9957,9958],{},"search your repositories and clone one"," straight into a new project — the same on-device token authenticates private clones. See ",[99,9961,1074],{"href":2338},[14,9963,9965],{"id":9964},"fetching-pulling-and-pushing","Fetching, pulling and pushing",[10,9967,9968,9969,9972,9973,9975,9976,9978],{},"A connection is also a ",[52,9970,9971],{},"fallback credential for git itself",". Fetch, Pull, Push and background fetching all run the real ",[22,9974,135],{}," on your machine, so they use your own setup first — a credential helper, an SSH key, whatever ",[22,9977,7263],{}," would use in a terminal. Nothing about that changes when you connect a provider.",[10,9980,9981,9982,9984],{},"What changes is what happens when that setup has nothing to offer. Plexus never shows a password prompt (a desktop app has no terminal for git to ask on, and a hidden prompt would just hang), so on a machine with no stored credentials an ",[22,9983,1200],{}," remote used to fail outright. Now, if the repository's remote points at a provider you've connected, Plexus retries the operation once using that connection — and it usually just works.",[10,9986,9987],{},"Some details worth knowing:",[331,9989,9990,9996,10014,10020,10026],{},[334,9991,9992,9995],{},[52,9993,9994],{},"Your own credentials always win — for Fetch, Pull and Push."," The connection is only tried after git's own attempt has failed, so a credential helper with wider access than your Plexus connection keeps being the one that authenticates. (Cloning from the repository search is the exception, and uses your connection directly: there is no repository yet for a helper to hold credentials for.)",[334,9997,9998,10001,10002,10005,10006,10009,10010,10013],{},[52,9999,10000],{},"The token is bound to that host."," A GitHub connection is only ever offered to ",[22,10003,10004],{},"github.com",", and a Bitbucket one only to ",[22,10007,10008],{},"bitbucket.org",". It is passed to git for that one command — never written into ",[22,10011,10012],{},".git\u002Fconfig",", and never into a remote URL.",[334,10015,10016,10019],{},[52,10017,10018],{},"Only the host that actually refused is retried."," If a repository has several remotes and the one that failed isn't on a provider you've connected — a company git server, say — Plexus doesn't try again; there is nothing it could authenticate with.",[334,10021,10022,10025],{},[52,10023,10024],{},"A connection that gets refused is rested for a few minutes."," If the provider itself turns the connection down — the account can't reach that repository, the grant was revoked, your organization hasn't authorized it — Plexus stops offering it for a short while rather than doubling every fetch with an attempt it knows will fail. Reconnecting the provider clears that straight away, so you never have to wait after following the error's own advice.",[334,10027,10028,10033],{},[52,10029,10030,10032],{},[22,10031,1203],{}," remotes are untouched."," They authenticate with your keys and agent; no token applies, so nothing is retried.",[47,10035,10036],{},[10,10037,10038,10039,320,10041,2703,10043,132],{},"If it still can't authenticate, the message says which host refused and what to do about it — connect the provider, fix your credential helper, or switch the remote to ",[22,10040,1203],{},[99,10042,3988],{"href":368},[99,10044,2381],{"href":373},[14,10046,10048],{"id":10047},"where-your-token-lives-what-leaves-your-device","Where your token lives — what leaves your device",[10,10050,10051,10052,10055,10056,10058],{},"Plexus uses a small ",[52,10053,10054],{},"managed sign-in service"," we run in the EU. When you connect, the provider hands back a short-lived authorization ",[52,10057,22],{},"; Plexus sends only that code to the service, which holds the OAuth app secret and exchanges it for your access token.",[47,10060,10061],{},[10,10062,10063,10066,10067,10070,10071,10074],{},[52,10064,10065],{},"The token is returned to your device and stored in your operating system's keychain — we don't keep it."," From then on, Plexus talks to GitHub or Bitbucket ",[52,10068,10069],{},"directly from your machine","; your repository names, code, and pull-request contents ",[52,10072,10073],{},"never pass through our servers",". Because the token lives locally, PR features keep working offline after you've signed in.",[10,10076,10077,10078,10081,10082,10085],{},"This is the managed ",[52,10079,10080],{},"connection"," service only — a broker, not a proxy. It is separate from the anonymous ",[99,10083,10084],{"href":471},"usage analytics"," Plexus collects, and neither one sends us Your Content.",[14,10087,10089],{"id":10088},"reconnect","Reconnect",[10,10091,10092,10093,10096,10097,10100,10101,10104,10105,10107],{},"Providers grant a token the permissions the app had ",[52,10094,10095],{},"at the moment you signed in",". If that set later changes — Plexus starts needing a permission it didn't before — your existing token keeps the narrower access, and refreshing it in the background won't widen it. Click ",[52,10098,10099],{},"Reconnect GitHub"," (or ",[52,10102,10103],{},"Reconnect Bitbucket",") in ",[52,10106,156],{}," to sign in again and pick up the new access.",[10,10109,10110],{},"Reconnecting never leaves you signed out: Plexus only replaces the stored token once the new sign-in succeeds, so cancelling the browser tab changes nothing.",[10,10112,10113,10114,10116],{},"You don't have to go looking for it: when Plexus can't reach your repositories, the repository picker offers the same ",[52,10115,10089],{}," inline and re-runs your search as soon as you're done.",[10,10118,10119],{},"Plexus also checks on its own, rather than waiting for something to fail. Shortly after startup — and every six hours or so while you work — it asks GitHub or Bitbucket what your stored token is actually allowed to do. That's one small request made from your machine with the token that's already there; nothing extra is sent to us.",[10,10121,10122,10123,853,10126,10129,10130,10100,10132,10134,10135,10138,10139,10141,10142,10149],{},"If the access no longer covers what Plexus needs, a notice names the missing permission — spelled the way the provider labels it, such as ",[52,10124,10125],{},"Workspace membership: Read",[52,10127,10128],{},"Account: Read"," — and offers ",[52,10131,10099],{},[52,10133,10103],{},") right there, so you sign in without leaving what you were doing. Plexus re-checks the access before telling you it worked. ",[52,10136,10137],{},"Not now"," puts that notice away and it stays away; ",[52,10140,156],{}," keeps warning you, with the status line reading ",[52,10143,10144,10145,10148],{},"Connected as ",[91,10146,10147],{},"your account"," — limited access",", until the access is confirmed restored. Signing in again is not what clears it — the confirmation is. So if a reconnect happens to land on the same narrow access, the warning correctly stays up. If the permissions change again later you'll get a fresh notice — dismissing one never silences the next.",[10,10151,10152,10153,10155],{},"That background check can only confirm part of what a connection needs. On Bitbucket it confirms that your workspaces are still visible, and there is no way to ask Bitbucket what else a connection covers, so everything beyond that is discovered when something is genuinely refused. A notice raised by a refusal is therefore only cleared by something that covers the ",[91,10154,4629],{}," permission — a check that passed for something else is not an all-clear, and Plexus no longer treats it as one.",[47,10157,10158],{},[10,10159,10160,10161,10164,10165,10167],{},"If you have been caught in a loop — a notice asking you to reconnect, a ",[52,10162,10163],{},"Bitbucket access restored"," message moments later, then the identical notice at the next repository search or pull-request refresh, and ",[52,10166,10137],{}," never making it stop — that is the loop this closes.",[10,10169,10170,10173],{},[52,10171,10172],{},"Reconnecting is the first thing to try."," It is the whole fix whenever your token simply predates a permission Plexus now needs, which is the common case. The other case is a permission that has to be enabled on the Plexus app registration at the provider — signing in again can't widen that one, however many times you do it. Plexus can only tell the two apart by trying, so it re-checks your access the moment you're back from the browser; if it still comes up short, it says plainly that signing in again did not widen the grant, stops offering the button, and asks you to report the permission it named. Reporting it is what fixes it. That outcome is remembered between restarts, so you don't meet the same round trip every time you open the app — and if the permission is later enabled and something else is missing, that's a different problem and you'll get a fresh notice.",[47,10175,10176],{},[10,10177,10178,10180,10181,10184],{},[52,10179,840],{}," lists every connected account under ",[52,10182,10183],{},"Connected accounts",", with the access the provider recorded for that connection. When Plexus asks you to report a permission it named, that list is the thing to copy into the report. A provider that recorded nothing says so rather than showing a blank.",[10,10186,10187,10188,10191,10192,10197],{},"Sometimes the provider stops accepting the sign-in altogether rather than narrowing it — a token that was revoked, or an account that changed. There is no missing permission to name in that case, so Plexus says so instead: the notice reads ",[52,10189,10190],{},"Bitbucket no longer accepts this connection"," (or GitHub), and the status line reads ",[52,10193,10144,10194,10196],{},[91,10195,10147],{}," — sign-in no longer accepted",". Reconnecting is the whole fix here, and it says that plainly.",[10,10199,10200,10201,10203,10204,8626,10207,10209,10210,8626,10213,10216],{},"You can change how this works in ",[52,10202,3296],{},". ",[52,10205,10206],{},"Check that provider connections still work",[52,10208,9180],{},") turns the whole thing off — no request is made and no notice appears — and ",[52,10211,10212],{},"How often to check provider connections (hours)",[52,10214,10215],{},"6",") sets the wait between checks of the same connection. Raise it on a metered connection or an account that's close to its provider's rate limits. Whatever the interval, Plexus still checks shortly after starting and straight away when a provider refuses one of its requests.",[14,10218,10220],{"id":10219},"when-plexus-cant-list-your-repositories","When Plexus can't list your repositories",[10,10222,10223,10224,10227],{},"If the repository picker reports that it couldn't access your repositories, ",[52,10225,10226],{},"Details"," on that message carries the provider's own explanation, which is usually enough to tell you what to do next. It opens on its own whenever signing in again isn't the whole answer, and sits collapsed when it is. On Bitbucket, where Plexus lists each of your workspaces separately, the explanation names the workspace that refused.",[10,10229,10230,10231,10234,10235,10237,10238,10240],{},"The message offers two ways forward, and leads with whichever suits the failure: ",[52,10232,10233],{},"Try again"," re-runs the search on the spot (the right first move for a dropped connection or a provider hiccup), while ",[52,10236,10089],{}," signs you in again (what fixes an expired token or a missing permission). ",[52,10239,10233],{}," stays available even while a sign-in tab is still open, so a search that failed for an unrelated reason is always one click from a retry.",[47,10242,10243],{"tone":69},[10,10244,10245,10248,10249,10251,10252,10254,10255,10258],{},[52,10246,10247],{},"Bitbucket: \"your credentials lack one or more required privilege scopes.\""," Listing your repositories needs Bitbucket's ",[52,10250,10125],{}," permission. Bitbucket grants permissions to the app itself rather than per sign-in, so a token issued before Plexus needed this one won't carry it — ",[52,10253,10089],{}," to get a fresh token. If reconnecting doesn't clear it, the permission is missing on the Plexus side and no amount of re-signing-in will help. Plexus checks your access again as soon as you're back from the browser, and only if that check still comes up short does it tell you the sign-in didn't widen anything and stop asking — instead of sending you round the same loop. That outcome is remembered between restarts, so a fresh start doesn't put you back at the beginning of the loop. It reports what the check found, never a guess at why, so please report it. Either way the ",[52,10256,10257],{},"URL"," tab still works: cloning only needs repository access, which you already have.",[14,10260,10262],{"id":10261},"disconnect","Disconnect",[10,10264,4123,10265,853,10268,4996,10271,10273],{},[52,10266,10267],{},"Disconnect GitHub",[52,10269,10270],{},"Disconnect Bitbucket",[52,10272,156],{}," to remove the stored token from your keychain. You can reconnect any time.",[10,10275,10276,10277,10280,10281,132],{},"Next: ",[99,10278,10279],{"href":1469},"open and track pull requests",". For how connections relate to what data leaves your device, see our ",[99,10282,472],{"href":471},{"title":33,"searchDepth":266,"depth":266,"links":10284},[10285,10286,10287,10288,10289,10290],{"id":9938,"depth":266,"text":9939},{"id":9964,"depth":266,"text":9965},{"id":10047,"depth":266,"text":10048},{"id":10088,"depth":266,"text":10089},{"id":10219,"depth":266,"text":10220},{"id":10261,"depth":266,"text":10262},"Connect GitHub or Bitbucket with one click so Plexus can open and track pull requests.","Integrations","PlugZap",{},"Git providers",40,{"title":9923,"description":10291},"docs\u002Fconnections","Xzb8xMWorP8J5KY2hdvDiGmi4OeIpRBZEk8_fF6Mid8",{"id":10301,"title":102,"body":10302,"description":12198,"extension":277,"group":12199,"icon":102,"meta":12200,"navTitle":102,"navigation":281,"order":12201,"path":101,"seo":12202,"stem":12203,"__hash__":12204},"docs\u002Fdocs\u002Fsettings.md",{"type":7,"value":10303,"toc":12179},[10304,10307,10311,10314,10320,10331,10339,10352,10356,10390,10402,10415,10437,10441,10468,10480,10497,10508,10521,10527,10530,10535,10540,10542,10560,10563,10566,10600,10605,10608,10611,10617,10622,10625,10643,10646,10650,10653,10695,10729,10737,10741,10744,10794,10796,10800,10803,10847,10851,10854,10898,10902,10905,10966,10968,10971,11014,11032,11035,11038,11041,11141,11144,11147,11273,11277,11280,11326,11329,11332,11466,11496,11500,11503,11549,11557,11560,11563,11566,11639,11642,11648,11694,11709,11711,11714,11834,11847,11850,11853,11933,11951,11959,11962,11965,12096,12108,12119,12131,12144,12155,12158],[10,10305,10306],{},"Plexus runs zero-config — every setting has a sensible default, so you only open Settings when you want to change one.",[14,10308,10310],{"id":10309},"layered-settings","Layered settings",[10,10312,10313],{},"Settings cascade through four layers, broadest to narrowest:",[27,10315,10318],{"className":10316,"code":10317,"language":485},[483],"Global  →  Workspace  →  Project  →  Session\n",[22,10319,10317],{"__ignoreMap":33},[10,10321,10322,10323,10326,10327,10330],{},"Each layer ",[52,10324,10325],{},"inherits"," from the one above until you ",[52,10328,10329],{},"override"," the value there — a more-specific layer always wins, and if no layer sets a value the built-in default applies. So you set a default once globally, override it for a single workspace, and override it again for one project inside that workspace.",[10,10332,10333,10334,1432,10336,10338],{},"A session inherits its effective values from its owning project. Settings that govern how a session is created or started — ",[52,10335,1316],{},[52,10337,5716],{}," — are decided before the session exists, so they always resolve from the project layer, never the session itself.",[47,10340,10341],{},[10,10342,10343,10344,10347,10348,4176,10350,132],{},"Settings live inside Plexus (the Settings UI, backed by Plexus's own store). There is no ",[22,10345,10346],{},".plexus.toml"," file to edit. Repo-committed lifecycle hooks are the one exception — those live in ",[22,10349,4893],{},[99,10351,389],{"href":388},[14,10353,10355],{"id":10354},"the-settings-ui","The Settings UI",[10,10357,10358,10359,1432,10362,1432,10364,1432,10367,1439,10370,10373,10374,1432,10377,1432,10379,1439,10382,10385,10386,1751,10388,132],{},"Open global Settings to edit defaults that apply everywhere. Rows are grouped into five pages — ",[52,10360,10361],{},"General",[52,10363,1303],{},[52,10365,10366],{},"Git & PRs",[52,10368,10369],{},"Worktrees & Hooks",[52,10371,10372],{},"Advanced"," — plus dedicated pages for ",[52,10375,10376],{},"Appearance",[52,10378,10295],{},[52,10380,10381],{},"Keybindings",[52,10383,10384],{},"About",", so you can find a setting without scrolling a flat list. Connecting GitHub or Bitbucket lives under ",[52,10387,10295],{},[99,10389,173],{"href":172},[10,10391,10392,10393,1432,10395,1432,10398,10401],{},"Within a page, related rows sit under a labelled section — ",[52,10394,2655],{},[52,10396,10397],{},"Code review",[52,10399,10400],{},"Fetching and remotes"," and so on — each with a one-line description of what the group covers. The reference below mirrors those sections exactly.",[10,10403,10404,10405,1432,10407,10410,10411,10414],{},"Every row shows a badge for where its current value comes from: ",[22,10406,1067],{},[22,10408,10409],{},"Inherited from"," a parent layer, or ",[22,10412,10413],{},"Set here",". When a row is set at the layer you're viewing, a reset button (↺) appears next to its control — click it to clear the override and fall back to the inherited or default value.",[47,10416,10417],{},[10,10418,10419,10420,1055,10423,2602,10425,1439,10427,1432,10430,1055,10432,2602,10435,132],{},"Looking for the model pickers? There's one next to each AI feature rather than in a single list: ",[52,10421,10422],{},"Model for the agent",[52,10424,4716],{},[52,10426,1303],{},[52,10428,10429],{},"Model for pull request descriptions",[52,10431,7234],{},[52,10433,10434],{},"Model for commit messages",[52,10436,10366],{},[105,10438,10440],{"id":10439},"overriding-at-a-workspace-or-project","Overriding at a workspace or project",[10,10442,10443,10444,10447,10448,10450,10451,8044,10453,10456,10457,10459,10460,10463,10464,10467],{},"Every scope has its own ",[52,10445,10446],{},"Settings…"," entry: a project's is in the ",[22,10449,1083],{}," menu on its sidebar row, and a workspace's is in the workspace menu in the app bar — or, if you set ",[52,10452,4267],{},[52,10454,10455],{},"All workspaces in the sidebar",", in the ",[22,10458,1083],{}," menu on the workspace's own row. At these scopes each ",[52,10461,10462],{},"section"," carries its own ",[52,10465,10466],{},"Override parent settings"," switch, next to its heading:",[331,10469,10470,10475],{},[334,10471,10472,10474],{},[52,10473,5652],{}," — every row in that section is read-only and shows the value it inherits, and from where. This is the default, so a new workspace or project changes nothing.",[334,10476,10477,10479],{},[52,10478,9180],{}," — that section's rows become editable; anything you change is an override applied to this scope and everything inside it.",[10,10481,10482,10483,10486,10487,1055,10490,10492,10493,10496],{},"Sections are independent: turning on ",[52,10484,10485],{},"Copied files"," for a project leaves ",[52,10488,10489],{},"Session folders",[52,10491,8326],{}," inheriting. Turning a switch back off unsets every override in ",[52,10494,10495],{},"that section"," at this layer, and leaves the rest of the page alone.",[10,10498,10499,10500,1055,10502,10504,10505,10507],{},"A page that only has a handful of settings at this scope — ",[52,10501,10361],{},[52,10503,10372],{},", where most rows are global-only — keeps a single ",[52,10506,10466],{}," toggle for the whole page instead. A section disappears entirely when none of its settings can be set at that layer.",[10,10509,10510,10511,8164,10513,10515,10516,10518,10519,132],{},"The lifecycle-hooks editor at the bottom of ",[52,10512,10369],{},[91,10514,168],{}," governed by the ",[52,10517,8326],{}," switch — it has its own per-layer inheritance, described in ",[99,10520,389],{"href":388},[10,10522,10523,10524,10526],{},"Some settings are global-only — the terminal shell, the agent path, diagnostics, Gravatar avatars, the editor's save mode, and all keybindings — and don't appear on workspace or project pages, because they describe the machine, not a scope. Everything on ",[52,10525,10376],{}," goes further: those are per-machine preferences that appear on no workspace or project page at all.",[14,10528,10376],{"id":10529},"appearance",[10,10531,10532,10534],{},[52,10533,1911],{}," holds three choices about how Plexus looks and how the sidebar is shaped. Each is a pair of cards with a small diagram of the layout it produces.",[47,10536,10537],{},[10,10538,10539],{},"Appearance is a per-machine preference. Unlike every other page in Settings it is never inherited by a workspace or project, and it will not appear on a project's own settings page — how Plexus looks on this computer is not a property of your repository. It is also not synced or carried by a backup.",[105,10541,8303],{"id":8302},[10,10543,10544,1432,10547,756,10550,10553,10554,10556,10557,10559],{},[52,10545,10546],{},"Dark",[52,10548,10549],{},"Light",[52,10551,10552],{},"Match system",", which is what a new install uses and which follows your operating system's light\u002Fdark setting as it changes during the day. The choice applies app-wide, including the ",[99,10555,379],{"href":378}," editor and the ",[99,10558,1970],{"href":1969},". The theme button in the app bar is a shortcut that swings between light and dark; this page is where you get back to following the system.",[105,10561,10562],{"id":5152},"Density",[10,10564,10565],{},"How much a session row says — a layout mode, not a spacing slider.",[10,10567,10568,10571,10572,1432,10574,1432,10576,756,10578,10580,10581,10583,10584,10587,10588,10591,10592,10595,10596,10599],{},[52,10569,10570],{},"Normal"," (the default) gives each session two lines: its name, then the branch it is on and what the agent is doing in words — ",[91,10573,1698],{},[91,10575,5159],{},[91,10577,1710],{},[91,10579,5127],{}," when the agent isn't mid-turn but ",[99,10582,2178],{"href":2177}," are still running. A single icon beside the branch name carries both facts about that branch: its ",[52,10585,10586],{},"shape"," marks a branch Plexus did not create, so you can see which sessions ",[99,10589,10590],{"href":368},"Rebase or Squash"," would be rewriting shared history on, and its ",[52,10593,10594],{},"colour"," is the ",[99,10597,10598],{"href":348},"pull-request status"," — click it to open the pull request.",[10,10601,10602,10604],{},[52,10603,9565],{}," is one line per session: the name, the coloured activity dot and the pull-request icon. It fits roughly twice as many sessions on screen, which is the point when five to ten are live at once.",[10,10606,10607],{},"You can also switch between them from the app bar, next to the Settings button.",[105,10609,4267],{"id":10610},"workspace-navigation",[10,10612,10613,10616],{},[52,10614,10615],{},"Switcher in the header"," (the default) keeps one workspace active at a time, chosen from the switcher in the app bar. The sidebar is then two levels — projects over sessions — so a project is the first thing you see and a session is one step in. The switcher's menu lists every workspace with its session count and how many are waiting on you.",[10,10618,10619,10621],{},[52,10620,10455],{}," restores the three-level tree: every workspace as a collapsible section, with its projects and their sessions nested inside.",[14,10623,5405],{"id":10624},"settings-reference",[10,10626,10627,10630,10631,10634,10635,10638,10639,10642],{},[52,10628,10629],{},"Where you set it"," is the narrowest layer a setting can change at: ",[52,10632,10633],{},"Global only"," means it's a per-machine choice; ",[52,10636,10637],{},"Global → Project"," means you set a default globally and can override it per workspace or project (sessions inherit from their project); ",[52,10640,10641],{},"Per session"," means it can be tuned for each individual session.",[105,10644,10361],{"id":10645},"general",[9645,10647,10649],{"id":10648},"notifications","Notifications",[10,10651,10652],{},"How Plexus gets your attention when a session needs you.",[190,10654,10655,10667],{},[193,10656,10657],{},[196,10658,10659,10661,10663,10665],{},[199,10660,5636],{},[199,10662,4743],{},[199,10664,1067],{},[199,10666,10629],{},[209,10668,10669,10682],{},[196,10670,10671,10675,10678,10680],{},[214,10672,10673],{},[52,10674,5367],{},[214,10676,10677],{},"Show an operating-system notification when a session finishes or needs your input",[214,10679,9180],{},[214,10681,10641],{},[196,10683,10684,10688,10691,10693],{},[214,10685,10686],{},[52,10687,5389],{},[214,10689,10690],{},"Play a sound when a session needs your attention (a preview button lets you test it)",[214,10692,5652],{},[214,10694,10641],{},[10,10696,10697,10700,10701,630,10704,1432,10707,1432,10710,1432,10713,1432,10716,10719,10720,10722,10723,10725,10726,10728],{},[52,10698,10699],{},"Custom sound."," By default the chime is synthesized in-app, but you can replace it with your own audio file under global Settings → General → ",[52,10702,10703],{},"Custom sound",[22,10705,10706],{},".wav",[22,10708,10709],{},".mp3",[22,10711,10712],{},".ogg",[22,10714,10715],{},".flac",[22,10717,10718],{},".m4a",", and more, up to 5 MB), directly beneath the ",[52,10721,5389],{}," toggle. Plexus copies the file you pick into its own data folder, so it stays on your machine and keeps working even if you move or delete the original; ",[52,10724,4772],{}," reverts to the built-in chime. This is a machine-wide choice (not per scope), and the per-session ",[52,10727,5389],{}," toggle still decides whether any sound plays.",[47,10730,10731],{},[10,10732,10733,10734,10736],{},"On Linux, desktop notifications use ",[22,10735,183],{}," — install it if alerts don't appear.",[9645,10738,10740],{"id":10739},"sessions-and-files","Sessions and files",[10,10742,10743],{},"What Plexus does with a session's folder, and with your edits.",[190,10745,10746,10758],{},[193,10747,10748],{},[196,10749,10750,10752,10754,10756],{},[199,10751,5636],{},[199,10753,4743],{},[199,10755,1067],{},[199,10757,10629],{},[209,10759,10760,10776],{},[196,10761,10762,10766,10772,10774],{},[214,10763,10764],{},[52,10765,4910],{},[214,10767,10768,10769,10771],{},"What happens to a session's working copy when you remove it: Delete immediately, Archive (keep a restorable copy), or Ask each time. The merged-pull-request cleanup below follows this setting too, but never stops to ask — so ",[52,10770,4956],{}," deletes there",[214,10773,4936],{},[214,10775,10637],{},[196,10777,10778,10783,10789,10792],{},[214,10779,10780],{},[52,10781,10782],{},"How the editor saves files",[214,10784,10785,10786,10788],{},"Whether the ",[99,10787,379],{"href":378}," editor saves only on the save shortcut or auto-saves shortly after you stop typing",[214,10790,10791],{},"Manual (save with Ctrl\u002F⌘+S)",[214,10793,10633],{},[105,10795,1303],{"id":9424},[9645,10797,10799],{"id":10798},"permissions-and-startup","Permissions and startup",[10,10801,10802],{},"How freely the agent runs, and whether sessions start themselves.",[190,10804,10805,10817],{},[193,10806,10807],{},[196,10808,10809,10811,10813,10815],{},[199,10810,5636],{},[199,10812,4743],{},[199,10814,1067],{},[199,10816,10629],{},[209,10818,10819,10832],{},[196,10820,10821,10825,10828,10830],{},[214,10822,10823],{},[52,10824,5716],{},[214,10826,10827],{},"Let the agent edit files and run commands without stopping to approve each action",[214,10829,9180],{},[214,10831,10637],{},[196,10833,10834,10838,10843,10845],{},[214,10835,10836],{},[52,10837,1316],{},[214,10839,10840,10841],{},"Launch the agent as soon as you open a brand-new session instead of waiting for ",[52,10842,1307],{},[214,10844,9180],{},[214,10846,10637],{},[9645,10848,10850],{"id":10849},"model-and-reasoning","Model and reasoning",[10,10852,10853],{},"Which model your sessions use, and how hard it thinks.",[190,10855,10856,10868],{},[193,10857,10858],{},[196,10859,10860,10862,10864,10866],{},[199,10861,5636],{},[199,10863,4743],{},[199,10865,1067],{},[199,10867,10629],{},[209,10869,10870,10884],{},[196,10871,10872,10876,10879,10882],{},[214,10873,10874],{},[52,10875,10422],{},[214,10877,10878],{},"Which model each session's agent runs with — Haiku (fastest), Sonnet (balanced), or Opus (most capable); Automatic uses the CLI's default. Applies the next time a session starts",[214,10880,10881],{},"Automatic (Claude's default)",[214,10883,10637],{},[196,10885,10886,10891,10894,10896],{},[214,10887,10888],{},[52,10889,10890],{},"Agent reasoning effort",[214,10892,10893],{},"How hard the agent thinks before acting — Low (fastest), Medium, High (more thorough) or Very high (slowest); Automatic uses the CLI's default. Applies the next time a session starts",[214,10895,10881],{},[214,10897,10637],{},[9645,10899,10901],{"id":10900},"input-and-controls","Input and controls",[10,10903,10904],{},"The compose box and buttons you see while a session runs.",[190,10906,10907,10919],{},[193,10908,10909],{},[196,10910,10911,10913,10915,10917],{},[199,10912,5636],{},[199,10914,4743],{},[199,10916,1067],{},[199,10918,10629],{},[209,10920,10921,10934,10947],{},[196,10922,10923,10927,10930,10932],{},[214,10924,10925],{},[52,10926,5649],{},[214,10928,10929],{},"Show the larger multi-line compose box automatically on a running session",[214,10931,5652],{},[214,10933,10637],{},[196,10935,10936,10940,10943,10945],{},[214,10937,10938],{},[52,10939,5662],{},[214,10941,10942],{},"Whether Ctrl+Enter (Cmd+Enter on Mac) sends your message immediately or just drops it into the input to review first",[214,10944,5652],{},[214,10946,10637],{},[196,10948,10949,10953,10962,10964],{},[214,10950,10951],{},[52,10952,5688],{},[214,10954,10955,10956,10958,10959,10961],{},"Show the ",[52,10957,5682],{}," control on the ",[99,10960,1303],{"href":1430}," tab, which rolls the conversation and its file edits back to a checkpoint",[214,10963,9180],{},[214,10965,10637],{},[9645,10967,4652],{"id":4651},[10,10969,10970],{},"The sidebar recap that refreshes when the agent stops.",[190,10972,10973,10985],{},[193,10974,10975],{},[196,10976,10977,10979,10981,10983],{},[199,10978,5636],{},[199,10980,4743],{},[199,10982,1067],{},[199,10984,10629],{},[209,10986,10987,11000],{},[196,10988,10989,10993,10996,10998],{},[214,10990,10991],{},[52,10992,4705],{},[214,10994,10995],{},"Show a sidebar with an AI-written summary of each session (each refresh spends one of your plan's turns; the summary is kept fresh incrementally and survives restarts)",[214,10997,5652],{},[214,10999,10637],{},[196,11001,11002,11006,11009,11012],{},[214,11003,11004],{},[52,11005,4716],{},[214,11007,11008],{},"Which model writes the session summary — Haiku (fastest), Sonnet (balanced), or Opus (most capable); Automatic uses the agent's default. Defaults to the fastest model so summaries load sooner",[214,11010,11011],{},"Haiku (fastest)",[214,11013,10637],{},[10,11015,11016,11017,11019,11020,11022,11023,1055,11025,11027,11028,11031],{},"This isn't the only place ",[52,11018,4705],{}," can be switched on. Every session has a ",[52,11021,4658],{}," button whether or not the setting is on, and opening that panel while it's off explains what a summary is and what it costs, with ",[52,11024,4692],{},[52,11026,4698],{}," — the same setting, written at the project or the global layer, followed by a first summary straight away. See ",[99,11029,4652],{"href":11030},"\u002Fdocs\u002Fsessions#session-summary",". Switching it back off is done here.",[105,11033,10366],{"id":11034},"git-prs",[9645,11036,2655],{"id":11037},"pull-requests",[10,11039,11040],{},"How Plexus drafts, tracks, and cleans up after a pull request.",[190,11042,11043,11055],{},[193,11044,11045],{},[196,11046,11047,11049,11051,11053],{},[199,11048,5636],{},[199,11050,4743],{},[199,11052,1067],{},[199,11054,10629],{},[209,11056,11057,11070,11083,11096,11112],{},[196,11058,11059,11063,11066,11068],{},[214,11060,11061],{},[52,11062,7876],{},[214,11064,11065],{},"When you create a pull request, let the agent draft the title and description from your changes",[214,11067,5652],{},[214,11069,10637],{},[196,11071,11072,11076,11079,11081],{},[214,11073,11074],{},[52,11075,10429],{},[214,11077,11078],{},"Which model drafts the pull request title and description; Automatic uses the agent's default",[214,11080,10881],{},[214,11082,10637],{},[196,11084,11085,11089,11092,11094],{},[214,11086,11087],{},[52,11088,8000],{},[214,11090,11091],{},"Keep a session's name in step with its pull request title (the underlying git branch keeps its name)",[214,11093,9180],{},[214,11095,10637],{},[196,11097,11098,11102,11108,11110],{},[214,11099,11100],{},[52,11101,6952],{},[214,11103,11104,11105,11107],{},"When you send ",[99,11106,1470],{"href":1469}," review comments to the agent, resolve those threads on GitHub or Bitbucket as soon as the agent finishes its turn. Resolving is public — the PR's author and other reviewers see it — and it happens when the agent stops, so you still verify the changes and push them yourself",[214,11109,5652],{},[214,11111,10637],{},[196,11113,11114,11118,11137,11139],{},[214,11115,11116],{},[52,11117,8009],{},[214,11119,11120,11121,11124,11125,11127,11128,11130,11131,11133,11134,11136],{},"Once Plexus notices a session's PR merged, clean that session up ",[52,11122,11123],{},"without asking",", following ",[52,11126,4910],{}," — and ",[52,11129,4956],{}," deletes here, because nothing is there to answer it. A delete removes the worktree even if it has uncommitted changes, and takes a ",[22,11132,4800],{}," branch Plexus cut if ",[52,11135,8019],{}," was left on the last time you removed a session by hand. A branch that existed before the session is always kept, and only a pull request Plexus saw while it was open qualifies",[214,11138,5652],{},[214,11140,10637],{},[9645,11142,10397],{"id":11143},"code-review",[10,11145,11146],{},"How the agent reviews your changes, and how the review-and-fix cycle behaves.",[190,11148,11149,11161],{},[193,11150,11151],{},[196,11152,11153,11155,11157,11159],{},[199,11154,5636],{},[199,11156,4743],{},[199,11158,1067],{},[199,11160,10629],{},[209,11162,11163,11180,11193,11206,11219,11233,11246,11259],{},[196,11164,11165,11169,11175,11178],{},[214,11166,11167],{},[52,11168,7067],{},[214,11170,11171,11172,11174],{},"The instructions the agent follows when it reviews a session's changes on the ",[99,11173,359],{"href":358}," tab",[214,11176,11177],{},"Senior-engineer prompt",[214,11179,10637],{},[196,11181,11182,11186,11189,11191],{},[214,11183,11184],{},[52,11185,7234],{},[214,11187,11188],{},"Which model reviews a session's changes and writes the inline comments; Automatic uses the agent's default",[214,11190,10881],{},[214,11192,10637],{},[196,11194,11195,11199,11202,11204],{},[214,11196,11197],{},[52,11198,7237],{},[214,11200,11201],{},"How hard the model thinks while reviewing. The review is a single pass that reads a diff and returns comments, so it gains less from a high setting than an agent that plans and edits",[214,11203,10881],{},[214,11205,10637],{},[196,11207,11208,11212,11215,11217],{},[214,11209,11210],{},[52,11211,7204],{},[214,11213,11214],{},"The most times the automatic review-and-fix loop runs before it stops on its own",[214,11216,8707],{},[214,11218,10637],{},[196,11220,11221,11225,11228,11231],{},[214,11222,11223],{},[52,11224,7247],{},[214,11226,11227],{},"What the fix agent is told before the comments themselves. The default keeps it to the comments it was given, so it doesn't wander into unrelated repository chores",[214,11229,11230],{},"Keep to the listed comments",[214,11232,10637],{},[196,11234,11235,11239,11242,11244],{},[214,11236,11237],{},[52,11238,7225],{},[214,11240,11241],{},"Which model applies the comments during a cycle. This is the expensive half of the cycle, so it is the setting to reach for first if rounds are taking too long",[214,11243,10881],{},[214,11245,10637],{},[196,11247,11248,11252,11255,11257],{},[214,11249,11250],{},[52,11251,7228],{},[214,11253,11254],{},"How hard the fix agent thinks while applying the comments",[214,11256,10881],{},[214,11258,10637],{},[196,11260,11261,11266,11269,11271],{},[214,11262,11263],{},[52,11264,11265],{},"Allow MCP servers in the review-and-fix agent",[214,11267,11268],{},"Start your configured MCP servers for the fix agent. Off by default — they add startup time to every round and applying a review comment rarely needs them",[214,11270,5652],{},[214,11272,10637],{},[9645,11274,11276],{"id":11275},"commit-messages","Commit messages",[10,11278,11279],{},"How the agent writes a message from your staged changes.",[190,11281,11282,11294],{},[193,11283,11284],{},[196,11285,11286,11288,11290,11292],{},[199,11287,5636],{},[199,11289,4743],{},[199,11291,1067],{},[199,11293,10629],{},[209,11295,11296,11313],{},[196,11297,11298,11302,11308,11311],{},[214,11299,11300],{},[52,11301,3488],{},[214,11303,11304,11305,11307],{},"The instructions the agent follows when it writes a commit message from your staged changes (the AI button on the session and ",[99,11306,1602],{"href":373}," Git tabs)",[214,11309,11310],{},"Imperative-subject prompt",[214,11312,10637],{},[196,11314,11315,11319,11322,11324],{},[214,11316,11317],{},[52,11318,10434],{},[214,11320,11321],{},"Which model drafts a commit message from your staged changes; Automatic uses the agent's default",[214,11323,10881],{},[214,11325,10637],{},[9645,11327,10400],{"id":11328},"fetching-and-remotes",[10,11330,11331],{},"What Plexus downloads from your remotes, and how often.",[190,11333,11334,11346],{},[193,11335,11336],{},[196,11337,11338,11340,11342,11344],{},[199,11339,5636],{},[199,11341,4743],{},[199,11343,1067],{},[199,11345,10629],{},[209,11347,11348,11368,11383,11397,11414,11434,11450],{},[196,11349,11350,11355,11364,11366],{},[214,11351,11352],{},[52,11353,11354],{},"Fetch from remotes automatically",[214,11356,11357,11358,11360,11361,11363],{},"Quietly run ",[22,11359,7263],{}," in the background so the branch ahead\u002Fbehind counts and the commit graph in the ",[99,11362,6241],{"href":373}," stay current. Only downloads — nothing is merged, checked out, or deleted — and pauses while the Plexus window is hidden",[214,11365,9180],{},[214,11367,10637],{},[196,11369,11370,11375,11378,11381],{},[214,11371,11372],{},[52,11373,11374],{},"How often to fetch the open Git tab (minutes)",[214,11376,11377],{},"How long to wait between automatic fetches for the project whose Git tab you have open. A minimum, not a deadline: a fetch is skipped while a git operation is already running. 1–1440 minutes",[214,11379,11380],{},"1",[214,11382,10637],{},[196,11384,11385,11390,11393,11395],{},[214,11386,11387],{},[52,11388,11389],{},"How often to fetch other projects (minutes)",[214,11391,11392],{},"How long to wait between automatic fetches for your other projects. Raise it if you have many projects, large repositories, or a metered connection. 1–1440 minutes",[214,11394,8707],{},[214,11396,10637],{},[196,11398,11399,11403,11410,11412],{},[214,11400,11401],{},[52,11402,3084],{},[214,11404,11405,11406,11409],{},"What a plain click of the Pull button does in the ",[99,11407,11408],{"href":373},"project's Git view",": Fetch all (download only), Fast-forward if possible, Fast-forward only, or Rebase",[214,11411,3092],{},[214,11413,10637],{},[196,11415,11416,11420,11430,11432],{},[214,11417,11418],{},[52,11419,7714],{},[214,11421,11422,11423,11425,11426,11429],{},"Show a badge on a session's ",[52,11424,136],{}," button counting the commits a rebase onto its base branch would bring in — see ",[99,11427,3988],{"href":11428},"\u002Fdocs\u002Fgit#when-a-rebase-is-worth-doing",". Plexus reads only the refs it has already fetched, so nothing extra is downloaded",[214,11431,9180],{},[214,11433,10637],{},[196,11435,11436,11440,11446,11448],{},[214,11437,11438],{},[52,11439,7643],{},[214,11441,11442,11443,11445],{},"Download the latest base branch from your remote before a session rebase or merge, so the session catches up with work that has landed since it started — see ",[99,11444,3988],{"href":4362},". Off reshapes onto the copy already on your machine and makes no network request",[214,11447,9180],{},[214,11449,10637],{},[196,11451,11452,11456,11462,11464],{},[214,11453,11454],{},[52,11455,2699],{},[214,11457,11458,11459,11461],{},"Look up commit-author avatars on Gravatar in the ",[99,11460,6241],{"href":373},"; off shows initials and makes no network requests",[214,11463,9180],{},[214,11465,10633],{},[10,11467,2199,11468,11470,11471,11473,11474,11476,11477,2703,11479,10203,11481,11483,11484,11486,11487,11490,11491,11493,11494,132],{},[52,11469,3084],{}," is also settable from the Pull button's own menu — its ",[52,11472,3101],{}," picker saves the choice for that project. That same menu carries ",[52,11475,3292],{},", which turns automatic fetching on or off for that one project. Automatic fetching talks only to the git remotes you configured, using the credentials git already has; see ",[99,11478,3212],{"href":7707},[99,11480,472],{"href":471},[52,11482,7714],{}," rides on those same fetches instead of making its own, so with automatic fetching off its count only changes when you fetch by hand. ",[52,11485,7643],{}," is the one that ",[91,11488,11489],{},"does"," make its own request — turn it off for a project on a metered connection, an offline machine, or a remote that wants to prompt you for credentials. Turning it off never blocks the operation, and neither does a failure: with the setting on, a download that doesn't succeed still lets the rebase or merge run against the last version Plexus fetched, with a warning that the base may be out of date. ",[52,11492,2699],{}," is a per-machine privacy switch: when on, Plexus queries Gravatar with a one-way SHA-256 hash of each commit author's email (never the address itself) and caches the results on disk; turned off, no request is made at all and the graph shows locally-drawn initials instead. See the ",[99,11495,472],{"href":471},[9645,11497,11499],{"id":11498},"connection-checks","Connection checks",[10,11501,11502],{},"How Plexus notices that a provider has narrowed what it granted.",[190,11504,11505,11517],{},[193,11506,11507],{},[196,11508,11509,11511,11513,11515],{},[199,11510,5636],{},[199,11512,4743],{},[199,11514,1067],{},[199,11516,10629],{},[209,11518,11519,11536],{},[196,11520,11521,11525,11532,11534],{},[214,11522,11523],{},[52,11524,10206],{},[214,11526,11527,11528,11531],{},"Quietly ask GitHub and Bitbucket whether the permissions they granted Plexus still cover what it needs, and tell you when they don't — see ",[99,11529,173],{"href":11530},"\u002Fdocs\u002Fconnections#reconnect",". Off makes no such request and shows no such notice",[214,11533,9180],{},[214,11535,10633],{},[196,11537,11538,11542,11545,11547],{},[214,11539,11540],{},[52,11541,10212],{},[214,11543,11544],{},"How long to wait between checks of the same connection. A minimum, not a schedule: Plexus also checks shortly after starting, and straight away when a provider refuses a request. 1–168 hours",[214,11546,10215],{},[214,11548,10633],{},[10,11550,11551,11553,11554,11556],{},[52,11552,10206],{}," is what catches a permission that was withdrawn on the provider's side — the kind of change that otherwise stays invisible until a repository search or a pull request fails. It talks only to GitHub or Bitbucket, from your machine, with the token already stored there. Raise ",[52,11555,10212],{}," on a metered connection or an account close to its provider's rate limits.",[105,11558,10369],{"id":11559},"worktrees-hooks",[9645,11561,10489],{"id":11562},"session-folders",[10,11564,11565],{},"Where each session gets its own copy of your project.",[190,11567,11568,11580],{},[193,11569,11570],{},[196,11571,11572,11574,11576,11578],{},[199,11573,5636],{},[199,11575,4743],{},[199,11577,1067],{},[199,11579,10629],{},[209,11581,11582,11595,11611],{},[196,11583,11584,11588,11591,11593],{},[214,11585,11586],{},[52,11587,9082],{},[214,11589,11590],{},"Subfolder under the project root where each session's working copy is created (session name appended)",[214,11592,9085],{},[214,11594,10637],{},[196,11596,11597,11601,11607,11609],{},[214,11598,11599],{},[52,11600,9105],{},[214,11602,11603,11604,11606],{},"Add new session folders to the repo's ",[22,11605,3440],{}," when they're inside the repo so they don't show up as changes",[214,11608,9180],{},[214,11610,10637],{},[196,11612,11613,11617,11631,11636],{},[214,11614,11615],{},[52,11616,4303],{},[214,11618,11619,11620,1055,11622,11624,11625,11627,11628,11630],{},"The base branch preselected in the New session dialog, in both ",[52,11621,1261],{},[52,11623,1265],{}," mode. Leave it unset and the default depends on the mode: the branch currently checked out in the project's main working copy when the session cuts a new branch, the repository's trunk (",[22,11626,4344],{},", usually ",[22,11629,3268],{},") when it starts on an existing branch",[214,11632,11633],{},[91,11634,11635],{},"(unset — see the description)",[214,11637,11638],{},"Project only",[9645,11640,10485],{"id":11641},"copied-files",[10,11643,11644,11645,11647],{},"Untracked files like ",[22,11646,1458],{}," that a new session needs.",[190,11649,11650,11662],{},[193,11651,11652],{},[196,11653,11654,11656,11658,11660],{},[199,11655,5636],{},[199,11657,4743],{},[199,11659,1067],{},[199,11661,10629],{},[209,11663,11664,11677],{},[196,11665,11666,11670,11673,11675],{},[214,11667,11668],{},[52,11669,8622],{},[214,11671,11672],{},"Copy the files and folders listed below into each new session's working copy when it's created",[214,11674,9180],{},[214,11676,10637],{},[196,11678,11679,11683,11686,11692],{},[214,11680,11681],{},[52,11682,8625],{},[214,11684,11685],{},"Paths (relative to the project root) copied into each new session's working copy, even if git normally ignores them",[214,11687,11688,1432,11690],{},[22,11689,1458],{},[22,11691,8631],{},[214,11693,10637],{},[47,11695,11696],{},[10,11697,11698,11700,11701,11703,11704,11706,11707,132],{},[52,11699,8622],{}," + ",[52,11702,8625],{}," are how gitignored files like ",[22,11705,1458],{}," reach a fresh worktree. See ",[99,11708,4535],{"href":1462},[9645,11710,8763],{"id":9277},[10,11712,11713],{},"A unique block of localhost ports per session, so two dev servers never collide.",[190,11715,11716,11728],{},[193,11717,11718],{},[196,11719,11720,11722,11724,11726],{},[199,11721,5636],{},[199,11723,4743],{},[199,11725,1067],{},[199,11727,10629],{},[209,11729,11730,11749,11763,11784,11815],{},[196,11731,11732,11736,11745,11747],{},[214,11733,11734],{},[52,11735,8755],{},[214,11737,11738,11739,11741,11742,11744],{},"Give each session its own block of 10 localhost ports, set as ",[22,11740,8681],{}," and friends in the environment of the agent, the session's terminal, and every lifecycle script (hook). Off also takes the ",[52,11743,8976],{}," button out of a session's tab strip, immediately and without a restart",[214,11746,9180],{},[214,11748,10637],{},[196,11750,11751,11755,11758,11761],{},[214,11752,11753],{},[52,11754,9513],{},[214,11756,11757],{},"The lowest port Plexus will hand out; 1024–32000",[214,11759,11760],{},"20000",[214,11762,10637],{},[196,11764,11765,11769,11779,11782],{},[214,11766,11767],{},[52,11768,9516],{},[214,11770,11771,11772,11774,11775,11778],{},"The range's ",[52,11773,9523],{}," upper bound: a whole block of 10 has to fit ",[91,11776,11777],{},"below"," it, so the default of 32000 hands out ports up to 31999. 1024–32767",[214,11780,11781],{},"32000",[214,11783,10637],{},[196,11785,11786,11790,11809,11813],{},[214,11787,11788],{},[52,11789,8734],{},[214,11791,11792,11793,11796,11797,11799,11800,1432,11802,1432,11804,1432,11806,11808],{},"Additional environment variable names set to the session's first port, on top of the ",[22,11794,11795],{},"PLEXUS_PORT*"," set Plexus always provides. Clear the list to set none. Names starting with ",[22,11798,9405],{},", and ones the toolchain needs (",[22,11801,44],{},[22,11803,9411],{},[22,11805,9414],{},[22,11807,9417],{},", the Anthropic credentials), are refused",[214,11810,11811],{},[22,11812,8728],{},[214,11814,10637],{},[196,11816,11817,11821,11827,11832],{},[214,11818,11819],{},[52,11820,8649],{},[214,11822,11823,11824,11826],{},"A file inside the session's working copy (relative to it, e.g. ",[22,11825,8631],{},") that Plexus keeps a marked block of the same port variables in, for tools that read a file rather than an environment. Empty writes nothing",[214,11828,11829],{},[91,11830,11831],{},"empty",[214,11833,10637],{},[47,11835,11836],{},[10,11837,11838,11839,11841,11842,11844,11845,132],{},"Plexus sets these variables; it does not detect your framework or add flags to your commands. A dev server that doesn't read ",[22,11840,8728],{}," — Vite, Astro, Angular — needs ",[22,11843,9495],{}," on its command. See ",[99,11846,8763],{"href":8644},[9645,11848,8326],{"id":11849},"lifecycle-hooks",[10,11851,11852],{},"Scripts that run as a session is created, started, or removed.",[190,11854,11855,11867],{},[193,11856,11857],{},[196,11858,11859,11861,11863,11865],{},[199,11860,5636],{},[199,11862,4743],{},[199,11864,1067],{},[199,11866,10629],{},[209,11868,11869,11885,11898,11916],{},[196,11870,11871,11875,11881,11883],{},[214,11872,11873],{},[52,11874,8912],{},[214,11876,11877,11878,11880],{},"If a ",[52,11879,4249],{}," lifecycle script (hook) exits with an error, stop the rest of the sequence instead of carrying on",[214,11882,9180],{},[214,11884,10637],{},[196,11886,11887,11891,11894,11896],{},[214,11888,11889],{},[52,11890,8920],{},[214,11892,11893],{},"How long a single lifecycle script may run before it's stopped and counted as failed. Raise it for a legitimately long setup step; 10–3600 seconds",[214,11895,8928],{},[214,11897,10637],{},[196,11899,11900,11904,11912,11914],{},[214,11901,11902],{},[52,11903,4897],{},[214,11905,11906,11907,11909,11910],{},"Run the scripts in a project's ",[22,11908,4893],{}," alongside the project hooks you set up in Plexus — see ",[99,11911,389],{"href":4901},[214,11913,9180],{},[214,11915,10637],{},[196,11917,11918,11922,11928,11931],{},[214,11919,11920],{},[52,11921,8802],{},[214,11923,11924,11925,11927],{},"The order a project's committed ",[22,11926,4893],{}," scripts and its app-managed project hooks run in: Repository hooks first, then your app-managed hooks; Your app-managed hooks first, then the repository's; or Repository hooks only (skip this project's app-managed hooks)",[214,11929,11930],{},"Repository hooks first, then your app-managed hooks (repoFirst)",[214,11932,10637],{},[47,11934,11935],{},[10,11936,11937,11939,11940,11942,11943,11945,11946,5589,11948,11950],{},[52,11938,4897],{}," is not an ordinary row: you flip it inside the hooks panel itself, next to the \"Repo hooks active\" banner, which appears on a project's ",[52,11941,10369],{}," page once that project's repository commits a ",[22,11944,4893],{}," — that per-project toggle is the only place it's editable, even though the value it starts from is the built-in default. ",[52,11947,8802],{},[91,11949,5228],{}," an ordinary row in this section, at every scope, so you can pick an order before any project has a manifest.",[10,11952,11953,11954,11956,11957,132],{},"The hooks editor itself sits at the bottom of this section. It keeps its own per-layer inheritance, so the section's ",[52,11955,10466],{}," switch does not govern it — see ",[99,11958,389],{"href":388},[105,11960,10372],{"id":11961},"advanced",[10,11963,11964],{},"This page isn't split into sections — most of its rows are per-machine escape hatches you'll rarely touch.",[190,11966,11967,11979],{},[193,11968,11969],{},[196,11970,11971,11973,11975,11977],{},[199,11972,5636],{},[199,11974,4743],{},[199,11976,1067],{},[199,11978,10629],{},[209,11980,11981,11995,12008,12026,12044,12061,12078],{},[196,11982,11983,11987,11990,11993],{},[214,11984,11985],{},[52,11986,1770],{},[214,11988,11989],{},"How many recently used sessions stay fully loaded so switching back is instant; past this the least-recently-used idle one is quietly shut down (0 = unlimited)",[214,11991,11992],{},"8",[214,11994,10637],{},[196,11996,11997,12001,12004,12006],{},[214,11998,11999],{},[52,12000,4144],{},[214,12002,12003],{},"The shell Plexus opens for the built-in terminal and in-app installers (Automatic picks the right one for your system, or point at a custom path)",[214,12005,8211],{},[214,12007,10633],{},[196,12009,12010,12014,12020,12024],{},[214,12011,12012],{},[52,12013,8261],{},[214,12015,12016,12017,12019],{},"The full path to the shell program to use, applied when ",[52,12018,4144],{}," is set to Custom",[214,12021,12022],{},[91,12023,11831],{},[214,12025,10633],{},[196,12027,12028,12032,12038,12042],{},[214,12029,12030],{},[52,12031,731],{},[214,12033,12034,12035,12037],{},"The full path to the ",[22,12036,24],{}," program; leave blank to let Plexus find it automatically",[214,12039,12040],{},[91,12041,11831],{},[214,12043,10633],{},[196,12045,12046,12050,12057,12059],{},[214,12047,12048],{},[52,12049,5522],{},[214,12051,12052,12053,12056],{},"Write a detailed troubleshooting log to ",[22,12054,12055],{},"plexus-diag.log"," in Plexus's data folder (applies live)",[214,12058,5652],{},[214,12060,10633],{},[196,12062,12063,12068,12074,12076],{},[214,12064,12065],{},[52,12066,12067],{},"Save diagnostics when a session gets stuck",[214,12069,12070,12071,12073],{},"When starting or resuming a session times out or is cancelled, append the recent activity trail to ",[22,12072,12055],{}," so it survives a restart",[214,12075,5652],{},[214,12077,10633],{},[196,12079,12080,12085,12091,12094],{},[214,12081,12082],{},[52,12083,12084],{},"Delete diagnostic logs after (days)",[214,12086,12087,12088,12090],{},"How many days of ",[22,12089,12055],{}," to keep; older lines are removed each time Plexus starts (0 keeps them forever)",[214,12092,12093],{},"7",[214,12095,10633],{},[10,12097,12098,12099,12101,12102,12105,12106,132],{},"Turning ",[52,12100,5522],{}," on reveals a ",[52,12103,12104],{},"Reveal log"," button that opens the folder containing ",[22,12107,12055],{},[10,12109,12110,12111,12114,12115,12118],{},"Beside it — and available whether or not the toggle is on — is ",[52,12112,12113],{},"Copy session diagnostics",". Plexus always keeps the last few hundred lines of session start\u002Fstop activity in memory: which stage each start reached, how long each one took, and where it stopped. The button copies them to your clipboard so you can paste them into a bug report. This is the quickest thing to send if a session won't start, and it works even if you only think to look ",[91,12116,12117],{},"after"," it happened.",[10,12120,12121,12122,12124,12125,12127,12128,12130],{},"That trail is kept in memory only. ",[52,12123,12067],{}," is what also writes it to ",[22,12126,12055],{}," when a start or resume times out or is cancelled, so it survives quitting Plexus. It's off by default because it puts repository paths, branch names and worktree folders on your disk; turn it on if you're chasing a session that only wedges occasionally. ",[52,12129,5522],{}," already covers this, so you don't need both.",[10,12132,12133,12134,12136,12137,12139,12140,12143],{},"The log file doesn't grow forever: every time Plexus starts it drops lines older than ",[52,12135,12084],{},", which is 7 by default. Set it to ",[22,12138,1774],{}," to keep everything — useful when you're capturing a problem that takes weeks to reappear. The change takes effect at the next launch. If you pinned the log somewhere yourself with the ",[22,12141,12142],{},"PLEXUS_DIAG"," environment variable, Plexus leaves that file alone.",[47,12145,12146],{},[10,12147,12148,12149,12151,12152,12154],{},"Session diagnostics contain session ids, stage names, timings, and repository paths — no file contents, prompts, or credentials. Plexus never transmits them on its own: the lines live in memory, and only reach your disk if you turn on one of the two settings above, your clipboard when you press ",[52,12150,12113],{},", or us if you attach them to a report yourself in ",[99,12153,1847],{"href":1846}," — which shows you the exact text first.",[105,12156,10381],{"id":12157},"keybindings",[10,12159,12160,12161,12164,12165,12168,12169,12172,12173,12175,12176,12178],{},"Every keyboard shortcut is a global-only setting. ",[22,12162,12163],{},"Mod"," matches ",[52,12166,12167],{},"Cmd"," on macOS and ",[52,12170,12171],{},"Ctrl"," on Windows\u002FLinux. Rebind, reset, or unbind each one in the ",[52,12174,10381],{}," panel — see ",[99,12177,2000],{"href":1476}," for the full set and their defaults.",{"title":33,"searchDepth":266,"depth":266,"links":12180},[12181,12182,12185,12190],{"id":10309,"depth":266,"text":10310},{"id":10354,"depth":266,"text":10355,"children":12183},[12184],{"id":10439,"depth":271,"text":10440},{"id":10529,"depth":266,"text":10376,"children":12186},[12187,12188,12189],{"id":8302,"depth":271,"text":8303},{"id":5152,"depth":271,"text":10562},{"id":10610,"depth":271,"text":4267},{"id":10624,"depth":266,"text":5405,"children":12191},[12192,12193,12194,12195,12196,12197],{"id":10645,"depth":271,"text":10361},{"id":9424,"depth":271,"text":1303},{"id":11034,"depth":271,"text":10366},{"id":11559,"depth":271,"text":10369},{"id":11961,"depth":271,"text":10372},{"id":12157,"depth":271,"text":10381},"Layered settings, and the ones worth knowing.","Reference",{},50,{"title":102,"description":12198},"docs\u002Fsettings","U5EGFyjWFFQu-8S2_n2GGIF0PLMjouM45Fyq5cBfHvY",{"id":12206,"title":2000,"body":12207,"description":12397,"extension":277,"group":12199,"icon":12398,"meta":12399,"navTitle":1477,"navigation":281,"order":12400,"path":1476,"seo":12401,"stem":12402,"__hash__":12403},"docs\u002Fdocs\u002Fshortcuts.md",{"type":7,"value":12208,"toc":12389},[12209,12212,12225,12227,12230,12233,12238,12241,12244,12248,12251,12259,12266,12269,12279,12283,12289,12292,12302,12306,12309,12321,12325,12331,12334,12338,12355,12358,12376,12383],[10,12210,12211],{},"Plexus is keyboard-driven: switch tabs, toggle panels, drive the agent, and run git operations without leaving the keyboard.",[47,12213,12214],{},[10,12215,12216,12218,12219,12221,12222,12224],{},[22,12217,1996],{}," is the platform command modifier — ",[52,12220,12167],{}," on macOS, ",[52,12223,12171],{}," on Windows and Linux. Every shortcut below uses it the same way.",[14,12226,5816],{"id":5844},[10,12228,12229],{},"Jump straight to any tab in the active session. These fire app-wide, even while the terminal is focused.",[1365,12231],{":rows":12232},"[[\"⌘1\",\"Switch to the Agent tab\"],[\"⌘2\",\"Switch to the Review tab\"],[\"⌘3\",\"Switch to the Explorer tab\"],[\"⌘4\",\"Switch to the Git tab\"]]",[10,12234,6736,12235,12237],{},[99,12236,1611],{"href":373}," the same chords drive its three tabs:",[1365,12239],{":rows":12240},"[[\"⌘1\",\"Switch to the project Dashboard tab\"],[\"⌘2\",\"Switch to the project Git tab\"],[\"⌘3\",\"Switch to the project Terminal tab\"]]",[10,12242,12243],{},"The project bindings are separate, independently rebindable actions that share their default combos with the session tab shortcuts. That's deliberate and safe: a session and a project are never in view at once, so Plexus routes the chord to whichever is active and doesn't count the overlap as a conflict.",[14,12245,12247],{"id":12246},"panels-views","Panels & views",[1365,12249],{":rows":12250},"[[\"⌘K\",\"Search sessions and projects\"],[\"⌘J\",\"Toggle the terminal panel\"],[\"⌘0\",\"Toggle the dashboard\"]]",[10,12252,12253,12255,12256,132],{},[22,12254,2274],{}," opens a search over every session and project in the tree — matching on a session's name,\nits branch, its project or its workspace — and pressing Enter both selects the result and\nreveals it in the sidebar, switching workspaces if it lives in another one. Archived sessions\naren't included; those live in the ",[99,12257,12258],{"href":1293},"Archived drawer",[10,12260,12261,12262,12265],{},"It shows the 50 best matches at a time. When there are more, the bar along the bottom says so\n(",[22,12263,12264],{},"50 of 128",") — type another character or two to narrow it.",[10,12267,12268],{},"It doesn't open while another dialog is on screen, so it can't navigate away from a New session\ndialog you are halfway through filling in — close that first.",[47,12270,12271],{"tone":69},[10,12272,12273,12275,12276,132],{},[22,12274,2274],{}," fires even while the agent terminal has focus, which is the point — but on Windows and\nLinux that means Ctrl+K no longer reaches the terminal, where it clears to the end of the\nline. Rebind or unbind it under ",[52,12277,12278],{},"Settings → Keybindings → Search sessions and projects",[14,12280,12282],{"id":12281},"agent-input","Agent input",[10,12284,12285,12286,12288],{},"Drive the ",[99,12287,1303],{"href":1430}," tab from the prompt box.",[1365,12290],{":rows":12291},"[[\"⌘I\",\"Toggle the rich (multi-line) input\"],[\"Enter\",\"Submit the prompt to the agent\"],[\"⇧Enter\",\"Insert a newline without submitting\"],[\"⌘C\",\"Copy the selected terminal text\"],[\"⌘V\",\"Paste the clipboard into the prompt\"],[\"⌃C\",\"Interrupt the running agent (when no text is selected)\"]]",[10,12293,12294,12295,8164,12297,12299,12300,132],{},"On Windows and Linux, ",[22,12296,5581],{},[22,12298,5592],{}," — it copies when text is selected and otherwise interrupts. Copy and paste work the same way in the bottom ",[99,12301,1970],{"href":1969},[14,12303,12305],{"id":12304},"editor","Editor",[1365,12307],{":rows":12308},"[[\"⌘S\",\"Save the active file in the Explorer editor\"]]",[10,12310,12311,12312,12314,12315,12318,12319,132],{},"Rebindable like every shortcut below (",[52,12313,5877],{},"). Prefer not to save by hand? Turn on auto-save under ",[52,12316,12317],{},"Settings → Editor"," and Plexus writes changes to disk as you type — see ",[99,12320,5767],{"href":378},[14,12322,12324],{"id":12323},"git-operations","Git operations",[10,12326,12327,12328,12330],{},"Reshape the session branch from anywhere — these fire even while the agent terminal is focused. They're destructive, so each carries two modifiers, and when you trigger one while typing in a terminal or input Plexus asks you to confirm before it rewrites the branch. See ",[99,12329,3988],{"href":368}," for what they do.",[1365,12332],{":rows":12333},"[[\"⌘⌥R\",\"Rebase the branch onto its base\"],[\"⌘⌥M\",\"Merge the base branch into the current branch\"],[\"⌘⌥S\",\"Squash the branch's commits\"]]",[14,12335,12337],{"id":12336},"customizing-shortcuts","Customizing shortcuts",[10,12339,12340,12341,12343,12344,12346,12347,12350,12351,12354],{},"Every binding above is editable under ",[52,12342,5877],{},". Click a row to ",[52,12345,4403],{}," a new combo — Plexus reads the physical key, so layout and Option-composed glyphs never garble it. You can also ",[52,12348,12349],{},"reset"," a binding to its default or ",[52,12352,12353],{},"unbind"," it entirely (leaving the action with no shortcut).",[10,12356,12357],{},"Two rules keep recordings safe:",[331,12359,12360,12363],{},[334,12361,12362],{},"Every binding needs at least one modifier, so a single keystroke can't fire an action while you work.",[334,12364,12365,12366,12368,12369,12372,12373,12375],{},"The destructive git ops require ",[52,12367,7584],{}," modifiers — a near-bare chord like ",[22,12370,12371],{},"⇧S"," or a reflexive ",[22,12374,5864],{}," won't trigger a rebase, merge, or squash.",[10,12377,12378,12379,12382],{},"Plexus flags ",[52,12380,12381],{},"conflicts"," when two actions share a combo. Every shortcut — navigation and git ops alike — fires while you're typing in a terminal or input, so the two-modifier rule above is what keeps a stray keystroke from triggering a rebase, merge, or squash mid-edit — and if one does fire while you're typing, Plexus confirms before rewriting the branch.",[10,12384,12385,12386,12388],{},"Bindings persist globally — see ",[99,12387,102],{"href":101}," for how scopes and overrides work.",{"title":33,"searchDepth":266,"depth":266,"links":12390},[12391,12392,12393,12394,12395,12396],{"id":5844,"depth":266,"text":5816},{"id":12246,"depth":266,"text":12247},{"id":12281,"depth":266,"text":12282},{"id":12304,"depth":266,"text":12305},{"id":12323,"depth":266,"text":12324},{"id":12336,"depth":266,"text":12337},"Plexus is keyboard-driven — almost every action has a shortcut.","Keyboard",{},51,{"title":2000,"description":12397},"docs\u002Fshortcuts","8PyNK0CVp8mkD_zNnd490aJ1iTMLHS3LATGEn4GtCfI",{"id":12405,"title":12406,"body":12407,"description":12605,"extension":277,"group":12199,"icon":12606,"meta":12607,"navTitle":1847,"navigation":281,"order":12608,"path":1846,"seo":12609,"stem":12610,"__hash__":12611},"docs\u002Fdocs\u002Ffeedback.md","Sending feedback",{"type":7,"value":12408,"toc":12595},[12409,12415,12421,12425,12460,12464,12473,12482,12489,12493,12499,12505,12514,12518,12527,12534,12538,12556,12566,12570,12586,12590],[10,12410,12411,12412,12414],{},"Plexus has a ",[52,12413,1847],{}," button in the app bar, next to the search field. Use it to tell us a bug, an idea, or anything else — it reaches the team directly, with no account and no issue tracker in the way.",[10,12416,12417,12418],{},"Because Plexus is local-first, this is the one place in the app where something you made can leave your machine. The dialog is built around showing you exactly what that is: ",[52,12419,12420],{},"nothing is sent until you press Send, and nothing is sent that the dialog did not put in front of you first.",[14,12422,12424],{"id":12423},"writing-a-report","Writing a report",[1114,12426,12427,12432,12445,12448,12455],{},[334,12428,4123,12429,12431],{},[52,12430,1847],{}," in the app bar.",[334,12433,12434,12435,1432,12438,853,12441,12444],{},"Pick ",[52,12436,12437],{},"Bug",[52,12439,12440],{},"Idea",[52,12442,12443],{},"Something else"," — it only decides which pile the report lands in.",[334,12446,12447],{},"Write your message. Anything up to 4,000 characters.",[334,12449,12450,12451,12454],{},"Optionally add your ",[52,12452,12453],{},"email address",". It is only used to reply to you. Leave it blank and the report is anonymous — we simply have no way to answer it.",[334,12456,2067,12457,132],{},[52,12458,12459],{},"Send feedback",[14,12461,12463],{"id":12462},"attaching-a-screenshot","Attaching a screenshot",[10,12465,2067,12466,12469,12470,12472],{},[52,12467,12468],{},"Attach screenshot"," and Plexus draws a picture of its own window. Nothing is captured before you press it, and you see the image before you send — with a ",[52,12471,4772],{}," button if you change your mind.",[47,12474,12475],{},[10,12476,12477,12478,12481],{},"It is a picture of the ",[52,12479,12480],{},"Plexus window only",", drawn by Plexus from its own interface rather than captured from your screen. It cannot contain another application, a second monitor, an overlay, or anything behind the window — and Plexus never asks macOS for screen-recording permission. It can of course contain whatever code and file names were on screen inside Plexus, which is why you get to look at it first.",[10,12483,12484,12485,12488],{},"If the drawing fails on your system, the dialog offers ",[52,12486,12487],{},"Choose an image…"," instead, so you can attach a screenshot you took yourself.",[14,12490,12492],{"id":12491},"attaching-diagnostic-logs","Attaching diagnostic logs",[10,12494,12495,12498],{},[52,12496,12497],{},"Include diagnostic logs"," is on by default. It attaches the trail Plexus keeps of what it was doing — which sessions started and stopped, how long each stage took, and where anything went wrong.",[10,12500,2067,12501,12504],{},[52,12502,12503],{},"Preview what's included"," to read the exact text that will be uploaded. That preview is not a summary; it is the bytes.",[47,12506,12507],{"tone":69},[10,12508,12509,12510,12513],{},"Passwords, tokens and API keys are blanked out automatically, and your home folder and username are replaced. The log deliberately ",[52,12511,12512],{},"keeps repository paths, branch names, worktree folder names, session ids and timings"," — those are what make it useful for finding your bug. Read the preview before sending if any of that is sensitive, or switch the toggle off.",[105,12515,12517],{"id":12516},"if-diagnostic-logging-is-off","If diagnostic logging is off",[10,12519,12520,12522,12523,12526],{},[52,12521,5522],{}," (Settings → Advanced) is off by default, so most of the time there is no log ",[91,12524,12525],{},"file"," to send. Plexus says so, and still attaches the activity trail it keeps in memory — which is usually enough on its own.",[10,12528,12529,12530,12533],{},"The dialog also offers to turn diagnostic logging on. That records much more detail, but it ",[52,12531,12532],{},"starts from the moment you turn it on"," — it cannot fill in the problem you are writing about. Turn it on, reproduce the problem, then send a second report.",[14,12535,12537],{"id":12536},"deleting-a-report-you-sent","Deleting a report you sent",[10,12539,12540,12541,12544,12545,12548,12549,12555],{},"Every report that goes through comes back with a ",[52,12542,12543],{},"reference code"," like ",[22,12546,12547],{},"PLX-7Q4M2-K3B9F",", and Plexus keeps it so you can find it later. Email that code to ",[52,12550,12551],{},[99,12552,12554],{"href":12553},"mailto:timo@codedwords.com","timo@codedwords.com"," and we delete the report and everything attached to it.",[10,12557,12558,12559,12562,12563,132],{},"You do not have to ask. Screenshots and diagnostic logs are deleted automatically after ",[52,12560,12561],{},"90 days",", and the message itself after ",[52,12564,12565],{},"12 months",[14,12567,12569],{"id":12568},"how-long-logs-stay-on-your-machine","How long logs stay on your machine",[10,12571,12572,12573,12575,12576,12579,12580,12582,12583,12585],{},"Separately from anything you send us, Plexus trims ",[22,12574,12055],{}," on your own disk each time it starts, keeping the last ",[52,12577,12578],{},"7 days",". You can change that — or switch it off entirely — with ",[52,12581,12084],{}," under Settings → Advanced; ",[22,12584,1774],{}," keeps them forever.",[14,12587,12589],{"id":12588},"what-we-do-with-it","What we do with it",[10,12591,12592,12593,132],{},"Reports are stored in the European Union and read by us. They are not used for advertising, not fed to an AI model, and not shared or sold. The full detail — what is always sent, what is only sent if you choose it, and what never is — is in the ",[99,12594,472],{"href":471},{"title":33,"searchDepth":266,"depth":266,"links":12596},[12597,12598,12599,12602,12603,12604],{"id":12423,"depth":266,"text":12424},{"id":12462,"depth":266,"text":12463},{"id":12491,"depth":266,"text":12492,"children":12600},[12601],{"id":12516,"depth":271,"text":12517},{"id":12536,"depth":266,"text":12537},{"id":12568,"depth":266,"text":12569},{"id":12588,"depth":266,"text":12589},"Write to the Plexus team from inside the app, and choose exactly what goes with it.","SquarePen",{},52,{"title":12406,"description":12605},"docs\u002Ffeedback","6c83rCNmVqI5HXfO0Ns_WspMHHb1UuNx6AohTHceqC4",1787146618683]