diff --git a/README.org b/README.org index 1a6e491..22386aa 100644 --- a/README.org +++ b/README.org @@ -15,6 +15,7 @@ #+html: reading output, #+html: sessions, #+html: shortcuts) · +#+html: Troubleshooting · #+html: Comparison · #+html: Advanced · #+html: Development

@@ -107,104 +108,6 @@ You may also define a shorter command name: After that, =M-x pi= starts or focuses the current project's pi session. -** Troubleshooting and first-run notes 🩺 - -*** No model is available - -Make sure the [[https://pi.dev/docs/latest/providers][Pi CLI is authenticated]] before expecting models to -appear: set a provider API key, or run =pi= in a terminal once and use -=/login=. Then make the running session pick up the new credentials: -press =C-c C-p R= (or =M-x pi-coding-agent-reload=) to restart the Pi -process without losing the conversation. - -*** Missing pi executable - -=pi-coding-agent= runs the command in =pi-coding-agent-executable=, -which defaults to =("pi")=. If Emacs cannot find =pi=, install the -CLI with the npm command from Quick Start on the host where Pi runs, -adjust the relevant search path, or customize -=pi-coding-agent-executable=. An example: - -#+begin_src emacs-lisp -;; npx users: -(setopt pi-coding-agent-executable - '("npx" "-y" "@earendil-works/pi-coding-agent@latest")) -#+end_src - -If startup says something like =env: node: No such file or directory=, -Emacs found the Pi launcher, but that launcher uses =/usr/bin/env node=. -=env= searches the subprocess =PATH=, not only Emacs =exec-path=. - -If you configure Node from init.el, update both: - -#+begin_src emacs-lisp -(let ((node-bin "/home/you/.local/share/pi-node/node-v22.23.1-linux-x64/bin")) - (add-to-list 'exec-path node-bin) - (setenv "PATH" (concat node-bin path-separator (or (getenv "PATH") "")))) -#+end_src - -*** Project-local Pi resources - -Pi does not show its project trust prompt in RPC mode. To make Emacs -sessions behave like the usual trusted project workflow, -=pi-coding-agent= passes =--approve= by default so project-local -=.pi= prompts, skills, settings, themes, and extensions are active. - -Set =pi-coding-agent-project-trust-policy= to =default= to pass no -trust flag and let Pi use its saved trust decisions and -=defaultProjectTrust=: - -#+begin_src emacs-lisp -;; Let Pi decide project trust from ~/.pi/agent/trust.json -;; and its global defaultProjectTrust setting. -(setopt pi-coding-agent-project-trust-policy 'default) -#+end_src - -Set it to =no-approve= to pass =--no-approve= and ignore -project-local Pi files for Emacs sessions. - -*** Grammar installation fails - -Grammar installation needs a working C compiler. Install =gcc= or -=cc=, then run: - -#+begin_src -M-x pi-coding-agent-install-grammars -#+end_src - -If an old system Markdown grammar is loaded and tables render -incorrectly, remove the old =libtree-sitter-markdown= from -=treesit-extra-load-path=, your Emacs tree-sitter directory, or your -system packages, then restart Emacs or run =M-x -pi-coding-agent-install-grammars=. - -*** Remote projects over TRAMP - -When the current project is a TRAMP directory, =pi-coding-agent= -starts the Pi CLI on the remote host. Install =pi= there. - -Authentication and configuration are remote too: run =pi= and =/login= -on that host, or set provider environment variables for the remote -process. Paths such as =~/.pi/agent/auth.json= and absolute entries in -=pi-coding-agent-executable= are interpreted on the host where Pi runs. - -For Emacs to find the command on the remote host, its directory must be -in TRAMP's remote search path; Emacs's local =exec-path= is not used. -Use an absolute path in =pi-coding-agent-executable=, or add the -executable's absolute remote directory to =tramp-remote-path=: - -#+begin_src emacs-lisp -(with-eval-after-load 'tramp - (add-to-list 'tramp-remote-path "/home/you/bin")) -#+end_src - -*** Transient is too old - -Emacs may load its bundled =transient= before the newer MELPA package. -If the menu complains about =transient=, set -=package-install-upgrade-built-in= to =t=, install or upgrade -=transient= from MELPA, and restart Emacs. - #+html: * Everyday workflow 🧭 @@ -318,6 +221,123 @@ and error thresholds. | =f= | chat | 🌿 Fork from the turn at point | | =q= | chat | 👋 Quit session | +#+html: +* Troubleshooting and first-run notes 🩺 + +#+html:
+#+html: No models are available: authenticate the Pi CLI + +Make sure the [[https://pi.dev/docs/latest/providers][Pi CLI is authenticated]] before expecting models to +appear: set a provider API key, or run =pi= in a terminal once and use +=/login=. Then make the running session pick up the new credentials: +press =C-c C-p R= (or =M-x pi-coding-agent-reload=) to restart the Pi +process without losing the conversation. + +#+html:
+ +#+html:
+#+html: Emacs cannot find the pi executable + +=pi-coding-agent= runs the command in =pi-coding-agent-executable=, +which defaults to =("pi")=. If Emacs cannot find =pi=, install the +CLI with the npm command from Quick Start on the host where Pi runs, +adjust the relevant search path, or customize +=pi-coding-agent-executable=. An example: + +#+begin_src emacs-lisp +;; npx users: +(setopt pi-coding-agent-executable + '("npx" "-y" "@earendil-works/pi-coding-agent@latest")) +#+end_src + +If startup says something like =env: node: No such file or directory=, +Emacs found the Pi launcher, but that launcher uses =/usr/bin/env node=. +=env= searches the subprocess =PATH=, not only Emacs =exec-path=. + +If you configure Node from init.el, update both: + +#+begin_src emacs-lisp +(let ((node-bin "/home/you/.local/share/pi-node/node-v22.23.1-linux-x64/bin")) + (add-to-list 'exec-path node-bin) + (setenv "PATH" (concat node-bin path-separator (or (getenv "PATH") "")))) +#+end_src + +#+html:
+ +#+html:
+#+html: Project-local .pi resources are not active + +Pi does not show its project trust prompt in RPC mode. To make Emacs +sessions behave like the usual trusted project workflow, +=pi-coding-agent= passes =--approve= by default so project-local +=.pi= prompts, skills, settings, themes, and extensions are active. + +Set =pi-coding-agent-project-trust-policy= to =default= to pass no +trust flag and let Pi use its saved trust decisions and +=defaultProjectTrust=: + +#+begin_src emacs-lisp +;; Let Pi decide project trust from ~/.pi/agent/trust.json +;; and its global defaultProjectTrust setting. +(setopt pi-coding-agent-project-trust-policy 'default) +#+end_src + +Set it to =no-approve= to pass =--no-approve= and ignore +project-local Pi files for Emacs sessions. + +#+html:
+ +#+html:
+#+html: Tree-sitter grammar installation fails + +Grammar installation needs a working C compiler. Install =gcc= or +=cc=, then run: + +#+begin_src +M-x pi-coding-agent-install-grammars +#+end_src + +If an old system Markdown grammar is loaded and tables render +incorrectly, remove the old =libtree-sitter-markdown= from +=treesit-extra-load-path=, your Emacs tree-sitter directory, or your +system packages, then restart Emacs or run =M-x +pi-coding-agent-install-grammars=. + +#+html:
+ +#+html:
+#+html: TRAMP projects run Pi on the remote host + +When the current project is a TRAMP directory, =pi-coding-agent= +starts the Pi CLI on the remote host. Install =pi= there. + +Authentication and configuration are remote too: run =pi= and =/login= +on that host, or set provider environment variables for the remote +process. Paths such as =~/.pi/agent/auth.json= and absolute entries in +=pi-coding-agent-executable= are interpreted on the host where Pi runs. + +For Emacs to find the command on the remote host, its directory must be +in TRAMP's remote search path; Emacs's local =exec-path= is not used. +Use an absolute path in =pi-coding-agent-executable=, or add the +executable's absolute remote directory to =tramp-remote-path=: + +#+begin_src emacs-lisp +(with-eval-after-load 'tramp + (add-to-list 'tramp-remote-path "/home/you/bin")) +#+end_src + +#+html:
+ +#+html:
+#+html: Emacs loads an old transient package + +Emacs may load its bundled =transient= before the newer MELPA package. +If the menu complains about =transient=, set +=package-install-upgrade-built-in= to =t=, install or upgrade +=transient= from MELPA, and restart Emacs. + +#+html:
+ #+html: * How does it compare to other Emacs LLM helpers? 🧭