Linux compatibility status

[acq23]

Hi,
I just installed a fresh copy of version 4.0.3 on Linux Mint 22.3.
I'm seeing some problems and what appear to be regressions (for example, issues #849 and #757). The Linux install issue that was fixed in version 3.0 is still present and unsolved.

Before I spend too much time on troubleshooting and bug fixing (I'm an entrepreneur and don't have much time for that), I would like to know the current status of the Linux compatibility layer.

Thank you in advance.

Best regards

[Drizzt321]

Not sure what you're seeing. When I installed v4.0.3 from scratch on Debian/stable, it's worked fine. It did create an X11 (so needed the X11-on-Wayland compatibility layer) window for it's initial setup, but that worked fine for me.

Now pure CLI only, dunno about that. Didn't end up realizing that was a maybe option.

[acq23]

Hi,
Thank you to have taken time to answer me.

I'm experiencing the same problems as reported in issues #849 and #757 regarding bash configuration, I’ve encountered issues with Linux machine detection and errors during configuration when trying to install a local TTS (which seems to work only on Mac) due to poor switch-case management and error handling.
So I investigated and found regressions in the bug logs — things that worked in v3 are no longer working. Seems the learning process is bugged too.

These problems have stopped me from going further, as I don’t want to spend a lot of time on something that currently feels quite unreliable or, worst, doesn't work as should be.

I’ve also seen a report about extremely high token consumption (not Linux-related): is this the case on average or is this specific to the use case of the person who reported it?

So my question is: Is this still in alpha or is it a beta stage? And is it worth investing time in it right now?

Finally, it’s not really clear from the documentation I’ve read so far how many external services PAI depends on: ElevenLabs for voice (if internal unavailable, like for Linux), Claude, Cloudflare (?), etc. and I found some readme.md be not up to date too, citing things apparently not existing anymore.

Hoping this helps you to understand why I asked that question in the original message.

Thank you very much

Have a nice day.

P.S..: I remark a sort of erratic Issues management too: some have answers, other are open from long time without any action, some are overlapping, etc. and it is not clear what direction the project is taking.

[zeddy303]

I'm in the same boat as @Drizzt321. I'm running PAI 4.0.3 on Debian inside a VPS and it works (I also have it on my macbook and another linux box). There are a few Mac-first polish bits (the local voice layer leans on macOS system voices, for instance), but honestly it's negligible and you can route around it.

On the bash issue specifically. The installer already detects your shell and writes to the right rc file. It adds one line, an alias:
alias pai='bun ~/.claude/PAI/Tools/pai.ts'

Plus a bun PATH export if bun isn't already on your path. That's the entire shell footprint. If you're on bash, it lands in .bashrc. The real bug I see is the post-install success screen tells everyone to source ~/.zshrc && pai regardless of shell. If you're on bash, just source ~/.bashrc && pai and you're running. Or copy the alias line yourself, it's one line.

Honest read though. If that level of config is already tripping you up, PAI is going to frustrate you at every turn. It's not a polished product and it was never pitched as one. It's a framework for people who want to get their hands dirty and build their own stack on top of it. Rough edges are part of the deal at this stage. In most cases, when I have been installing it before, I would have PAI help solve the problem I was coming up with (or use Claude separately).

On external dependencies, those are listed (Bun, Claude Code, etc), Claude (Anthropic API) is the brain, that's the one required thing. Everything else is optional and you turn it on per-feature. ElevenLabs for cloud TTS (especially relevant on Linux since you lose the Mac voice path). Cloudflare Workers for Flows and Pipelines if you want scheduled automations, skip it otherwise. A handful of per-skill API keys (OpenAI and so on) only if you use those skills.

You're right that some docs are stale. PRs fix that faster than waiting on Daniel.

Alpha vs beta isn't really the right framing. It's personal infrastructure that Daniel and the community iterate on in public. If you need stable-and-supported right now, this isn't that yet. If you want to learn by breaking things and fixing them, it's a good fit.

[acq23]

Thank you very much.

Ok, undestood about the bashrc.

I started to ask PAI for solutions, to implement them and to log them. I have not tested the bashrc stuff (MOD-005).
I attach the up-to-date version of problems/solutions found (jq presence, learning system, etc.): maybe will be useful for someone expert on coding (not me obviously).

I attach the screenshots of a fresh install where Claude Code did not automatically installed as in my first install: bizarre...

Best regards

PAI-MODIFICATIONS.md

[zeddy303]

Did you check to see if the alias was put in the .bashrc filie? Also, I'm questioning if claude code is installed even. It says in the beginning it isn't but didn't see it get installed in the screenshots.

run:
which claude
to confirm it's installed. Could have silently failed.

The installation IS funky and needs a bit of finagling. But I just saw Daniel on the Leo Laporte podcast and said version 5 is coming out soon 🤞

[acq23]

I just executed the source command before running, so I suppose it was correctly set because it runs.

No, Claude is not auto-installed in the current installation procedure: it is confirmed by "which claude" returning nothing.
I tried on 2 separate Linux environments with 2 different distros (one on a VM guest the other on the host) so I suppose it is not related to my specific environment: the April the 12th was all installing flawlessly.

JFYI I don't know if could be useful to someone, and I don't know if someone already did it, but I created a new config and 2 scripts to run on the same machine PAI and Claude Code CLI asynchronously without any conflict (at least from my little tests) . Separated memory, skills root, etc. BUT common Claude Code CLI.
Just to avoid to create a new VM (even if that would have taken me less time to do): learning...

[quamye]

Hi,
Thank you to everyone who has shared their experience with PAI on Linux. I wanted to add my own feedback because I appear to be running into a similar set of issues, and I am now trying to decide whether it is worth continuing to troubleshoot on Linux or whether I should start over with a fresh Mac installation instead.

At this point, I have most of the core PAI components running, and I was eventually able to get important parts of the stack working, including Open WebUI restoration and the VoiceServer backend. However, the overall Linux experience has been much more difficult and fragile than I expected, particularly when trying to get the voice workflow working cleanly from end to end.

The main problems I encountered include:

Inconsistent Open WebUI restore and rebuild behavior
confusion between custom images, official images, and attached Docker volumes
voice integration issues where the backend was functioning, but the frontend kept calling the wrong path
repeated fallback notifications such as “Task completed” instead of proper assistant speech
multiple competing voice-caller paths in the frontend
difficulty determining whether the root cause was Linux compatibility, Open WebUI, PAI VoiceServer, or my own custom modifications
documentation gaps around what is officially supported on Linux versus what is still effectively Mac-first or dependent on community workarounds

To be clear, I did eventually confirm that the voice backend itself can work on Linux. In my case, the Bun VoiceServer was able to generate MP3 files correctly, return audio URLs, and run under systemd without issue. So Linux support is clearly possible. The real problem is that the integration layer feels brittle and not very predictable, especially when trying to connect Open WebUI cleanly to the voice system without duplicate triggers, fallback behavior, or conflicting paths.

At this stage, my concern is less, “Can Linux technically run PAI?” and more, “How stable and repeatable is the Linux path for a normal user who does not want to spend days debugging interactions between Docker, Open WebUI, Bun, voice services, and incomplete or outdated documentation?”

Because of that, I am seriously considering starting again with a fresh Mac installation, mainly to compare the experience and see whether the voice path is more native and less fragile there.

So my questions are:

Is Linux currently considered a first-class path for the full PAI experience, including voice workflows, or is it still more of an advanced-user / community-supported path?
Is the voice stack still effectively Mac-first, with Linux requiring extra manual integration?
For someone who wants a stable and repeatable setup, is Mac currently the more reliable option?
Is there an updated recommended architecture for Linux users who want Open WebUI + PAI + VoiceServer working together cleanly?

I am sharing this as constructive feedback, not criticism. The project is clearly powerful, and I can see the potential. But from my experience, the Linux path, especially around voice, still feels harder and less predictable than it should be.

Thank you very much.

Best regards

Ronald

[Drizzt321]

Well, I've never done the voice output, actually disabled it from even attempting it. Eventually I'll aim to have some level of voice interaction, but doesn't really reflect the way I feel like working at this moment.

Otherwise, not sure where Open WebUI comes into play for PAI, since that (from my limited knowledge and research) doesn't look like it's meant to interact/use Claude Code like what it sounds like you're trying to use it for? I'm a bit confused how that comes into the picture. How is your setup intended to be used with that?

Aside from the voice server stuff, I've not faced any significant issues. I'm running it right on my terminal, no Docker containers, or anything like that. Just did what the instructions said, copy the .claude/ from the release dir to my ~/.claude, run the installation and go from there.

[quamye]

@Drizzt321 Hi,

Thank you very much for the clarification. That actually helps a lot.

I think the difference is that my setup is not just a standard terminal-based PAI + Claude Code workflow. I have been trying to integrate PAI into a broader platform that includes Open WebUI, Dockerized services, and voice output through the VoiceServer.

So I now understand that when you say Linux is working fine in your case, that is for the core CLI/terminal workflow, without Open WebUI and without voice. That makes sense, and it also explains why my experience has been much more complex.

From what I have seen so far, the core backend pieces can work on Linux, including the Bun VoiceServer, but the fragile part seems to be the integration layer between Open WebUI, Docker, and voice routing. So I think my issues are less about basic PAI installation on Linux, and more about running a custom architecture on top of it.

Your reply is helpful because it clarifies that Open WebUI is not really part of the standard path you are using with PAI, and that voice is also outside the path you have validated yourself.

That helps me separate:

core PAI Linux support
from
custom Open WebUI + voice integration challenges

Thank you again. That distinction is very useful.

Best regards

Ron.

[acq23]

I would like to provide some context to help the team better understand the tone and intent behind my messages.

Over my 30+ years of presence on the web, I have rarely commented on projects or products.
I maintain no personal social media accounts, with the sole exception of LinkedIn for professional purposes.
I value my time highly and am very selective about how I spend it.
Therefore, if I take the time to analyze issues and provide feedback, it is solely because I care about the project and want to contribute constructively — not to rant or express personal frustration.

First of all, thank you to everyone involved in this project for your hard work.

After approximately one week of intensive use (on Linux Mint, Pro plan, primarily with Sonnet 4.6 and occasional interaction with Opus 4.7), here are the main issues I have encountered:

1. Learning System Does Not Work as Expected

The system adds comments and keeps scores up to date, but the learned information is simply not taken into account during subsequent interactions. When I asked the AI to fix this, it identified and corrected some files, but found two files that appear to be dead-ends. In the AI’s own opinion (PAI), the learning system fails because these two files are never invoked. As a result, the system continues to repeat the same errors. This behavior seems to partially match an existing bug report.

2. Failure to Follow Its Own PAI Directives

The AI frequently fails to adhere to its own PAI directives, even after explicit enforcement attempts (CLAUDE.md modifications among others). It often ignores or skips the provided configuration. Instead of relying on actual project facts and files, it tends to answer from general knowledge.

Simple tests to reproduce this include:

• Asking for the value of CLAUDE_CONFIG_DIR after changing it.
• Creating a skill that overlaps with an existing one.
• Requesting information related to PAI scaffolding and best practices — the AI does not respect the routing chain defined in the markdown files.

Example:

❯ I want you to add a proposal template artifact to be used to create client proposals: please find me one that follows best practices, is clean, no more than 6 pages, and save it.

Read 1 file (ctrl+o to expand)

● Bash(curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"message": "Entering the Algorithm", "voice_id": "fTtv3eikoepIosk8dTZ5", …)
⎿ Error: Exit code 7

● ♻︎ Entering the PAI ALGORITHM… (v3.7.0) ═════════════
 🗒️ TASK: Find and save best-practice client proposal template

● Bash(mkdir -p /home/d/.claude/MEMORY/WORK/20260417-000001_client-proposal-template)

3. Routing Failures

The routing mechanism frequently fails to follow the intended directory structure and decision flow.
The same routing issues were observed when testing with Opus 4.7, suggesting an intrinsic problem in the system.

4. Inconsistent Directory Handling and Superficial Exploration

I also noticed inconsistencies in how the AI explores the PAI structure, which can lead to errors.
In one case, the AI behaved superficially: it stopped searching after finding a “business” directory and did not traverse all directories as explicitly instructed. When this was pointed out, it then proposed the other directory.
Inconsistencies from the README files define the intended structure:

| BUSINESS/ | Business context — company info, media kits, templates |
WORK/
├── README.md # This file
├── Consulting/ # Client-specific context
│ ├── templates/ # Proposal/report templates
│ └── clients/ # Per-client context files
└── Resources/ # Professional resources

Example:

❯ 1 you don't read your own architecture to understand where to save this file. Look at the USER folder and read the README files..

Read 2 files (ctrl+o to expand)

● The proposal template belongs in PAI/USER/BUSINESS/TEMPLATES/. Let me now build it.

Read 1 file, listed 1 directory (ctrl+o to expand)

● Now I have full context. Creating the template tailored to his AI automation/consulting business targeting USA professional services.

● Bash(mkdir -p /home/d/.claude/PAI/USER/BUSINESS/TEMPLATES && echo "done")
⎿ Interrupted · What should Claude do instead?

❯ 3 have you read ALL the README in USER?

Searched for 1 pattern, read 1 file (ctrl+o to expand)

● The correct location is PAI/USER/WORK/Consulting/templates/. Let me check what exists there and then build the template.

5. Error Handling Issues

Error handling appears to be either non-functional or failing silently.

6. Processing of requests that cannot be fully executed due to missing components

For example, when I deliberately requested the AI to create an image, the process initiated the media skill and became stuck while searching for the required API keys in order to delegate the task to an AI with visual capabilities. The operation should not have been started in the first place, given the existing constraints.

To avoid unnecessary consumption of time and tokens, such requests should be rejected early with a clear explanation rather than partially executed.

---

In addition to the findings listed above, it seems that the AI is currently handling too many tasks that should be deterministic. It frequently fails to follow basic discovery of the infrastructure by adhering to its own directives, starting from the PAI algorithm and the CLAUDE.md file.

I hope the upcoming v5 release will address some of these foundational problems or, at a minimum, provide clearer guidance on the correct way to use PAI.

Kind regards

[Drizzt321]

I just put in PR #1083 to address the rule adherence, and also links to my gist https://gist.github.com/Drizzt321/a4c567f0d263701152bf4e13c17855f1 which gives instructions to apply it to your current installation. It's been night and day when it comes to rule adherence.

[quamye]

@Drizzt321 Thank you again.

[acq23]

Thank you, I 'll read it.
Fun fact: I asked PAI to use Council and Red team to decide what rules should be moved from STEERING to CLAUDE.md.
Moved them.
Added a rule to read every README before a conception task to test the behavior.
During the first one it just violated it.

Rule Violated

CLAUDE.md §Critical Rules — Memory refresh on conception/change tasks:

FIRST mandatory action (before any thinking, planning, or response): Recursively read ALL README.md, CLAUDE.md, and other .md rule/documentation files in ~/.claude/ and all its subdirectories. After refreshing, explicitly confirm in your reasoning (briefly) that you have done so, then proceed.

What Happened

The entire session was a series of conception/change tasks. The rule fired zero times. Neither the recursive read nor the explicit confirmation occurred at any point.

[Drizzt321]

I'd be cautious, read where (higher or lower) in the file that is, other rules that exist. I've found the models tend to take any escape hatch they can, to either charge ahead or give in to their inclinations. If there's an earlier rule that might allow for not reading the README.md, it'll probably take it.

That's also probably not a good rule. There's a lot of .md files in PAI and ~/claude/ in general. Many are skill files, the general routing, preferences for specific skills, etc. And having it read them does NOT mean that they're in the special #mdClaude memory space. You'll want to use @<file> like I have it in my gist, to do that. I'd recommend going that route, rather than what you're trying to do.