Termux (Android) Setup

Atomic runs on Android via Termux, a terminal emulator and Linux environment for Android.

Termux uses Android's bionic libc, not Alpine's musl libc. Do not run the root install.sh there. Atomic's glibc and musl Linux release archives are not Android packages and do not provide a Termux target. Use the npm path below.

Android ARM64 still has no Atomic native target, so musl support does not change Termux's native-addon limitations.

Prerequisites

1. Install Termux from GitHub or F-Droid (not Google Play, that version is deprecated)
2. Install Termux:API from GitHub or F-Droid for clipboard and other device integrations

Installation

# Update packages
pkg update && pkg upgrade

# Install dependencies
pkg install nodejs termux-api git

# Install Atomic with npm (included with Termux's nodejs package)
npm install -g @bastani/atomic

# If you have installed Bun separately in Termux, you can use Bun instead:
# bun add -g @bastani/atomic

# Create config directory
mkdir -p ~/.atomic/agent

# Run Atomic
atomic

Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add --ignore-scripts to the install command.

Clipboard Support

Clipboard operations use termux-clipboard-set and termux-clipboard-get when running in Termux. The Termux:API app must be installed for these to work.

Image clipboard is not supported on Termux (the ctrl+v image paste feature will not work).

Example AGENTS.md for Termux

Create ~/.atomic/agent/AGENTS.md to help the agent understand the Termux environment:

# Agent Environment: Termux on Android

## Location
- **OS**: Android (Termux terminal emulator)
- **Home**: `/data/data/com.termux/files/home`
- **Prefix**: `/data/data/com.termux/files/usr`
- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)

## Opening URLs
```bash
termux-open-url "https://example.com"
```

## Opening Files
```bash
termux-open file.pdf          # Opens with default app
termux-open --chooser image.jpg      # Choose app
```

## Clipboard
```bash
termux-clipboard-set "text"   # Copy
termux-clipboard-get          # Paste
```

## Notifications
```bash
termux-notification -t "Title" -c "Content"
```

## Device Info
```bash
termux-battery-status         # Battery info
termux-wifi-connectioninfo    # WiFi info
termux-telephony-deviceinfo   # Device info
```

## Sharing
```bash
termux-share -a send file.txt # Share file
```

## Other Useful Commands
```bash
termux-toast "message"        # Quick toast popup
termux-vibrate                # Vibrate device
termux-tts-speak "hello"      # Text to speech
termux-camera-photo out.jpg   # Take photo
```

## Notes
- Termux:API app must be installed for `termux-*` commands
- Use `pkg install termux-api` for the command-line tools
- Storage permission needed for `/storage/emulated/0` access

Limitations

• No image clipboard: Termux clipboard API only supports text
• No Atomic native target on Android ARM64: Termux uses Android's bionic libc rather than Alpine's musl libc, so Alpine musl archives are not usable as Termux targets; optional native dependencies such as the clipboard module are unavailable and skipped during installation
• Storage access: To access files in /storage/emulated/0 (Downloads, etc.), run termux-setup-storage once to grant permissions

Troubleshooting

Clipboard not working

Ensure both apps are installed:

1. Termux (from GitHub or F-Droid)
2. Termux:API (from GitHub or F-Droid)

Then install the CLI tools:

pkg install termux-api

Permission denied for shared storage

Run once to grant storage permissions:

termux-setup-storage

Package installation issues

Termux does not currently provide an official pkg install bun package. On a fresh Termux install, use npm from the nodejs package; use Bun only if you installed it separately for your device.

If npm fails, try clearing the cache before retrying:

npm cache clean --force
npm install -g @bastani/atomic