# termux/termuxam architecture

> Architecture diagram of the GitHub repository termux/termuxam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/termux/termuxam
- Repository: https://github.com/termux/termuxam

## Overview

This repository reimplements Android’s `am` command for use from an app, addressing the Oreo-era restriction described in the README. The principal workflow is shell invocation, command/intent argument handling, then Activity Manager operations through a version-tolerant reflective interface. The code also includes compatibility support for Android’s hidden APIs and caller context. The README documents activity starts and broadcasts; the source index indicates additional service operations. Unsampled implementation details and wrapper-script internals are not inferred.

Main entry points: [`app/src/main/java/com/termux/termuxam/Am.java`](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/Am.java) (AM command), [`app/src/main/java/com/termux/termuxam/IActivityManager.java`](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/IActivityManager.java) (Activity operations), [`app/src/main/java/com/termux/termuxam/PermissionUtils.java`](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/PermissionUtils.java) (Permission checks), [`app/src/main/java/com/termux/termuxam/ShellCommand.java`](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/ShellCommand.java) (Argument reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_am["AM command<br/>[Am.java]"]
  node_base["Base command<br/>[BaseCommand.java]"]
  node_shellcmd["Argument reader<br/>[ShellCommand.java]"]
  node_intentcmd["Intent arguments<br/>[IntentCmd.java]"]
end

subgraph group_ops["Activity operations"]
  node_iam["Activity operations"]
  node_activityconstants["Activity constants"]
  node_receiver["Broadcast receiver stub"]
end

subgraph group_compat["Android compatibility"]
  node_crossversion["Method adaptation"]
  node_fakecontext["Caller context<br/>[FakeContext.java]"]
  node_workarounds["Platform workarounds<br/>[Workarounds.java]"]
  node_permissions["Permission checks"]
  node_servicemanager["Service lookup stub"]
  node_appops["App-ops interface stub"]
end

subgraph group_support["Runtime support"]
  node_reflection["Reflection utilities"]
  node_invoke["Invocation results<br/>[InvokeResult.java]"]
  node_methodresult["Method results"]
  node_logger["Logger<br/>[Logger.java]"]
end

node_shell(("Shell user"))
node_platformam["Android ActivityManager"]

node_shell -->|"invokes"| node_am
node_am -->|"uses"| node_base
node_base -->|"uses"| node_shellcmd
node_am -.->|"reads arguments"| node_shellcmd
node_am -->|"parses intents"| node_intentcmd
node_intentcmd -->|"reads arguments"| node_shellcmd
node_am -->|"dispatches operations"| node_iam
node_iam -->|"reflectively invokes"| node_platformam
node_iam -->|"adapts methods"| node_crossversion
node_iam -->|"uses context"| node_fakecontext
node_iam -->|"applies workarounds"| node_workarounds
node_iam -->|"uses receiver"| node_receiver
node_am -->|"checks permissions"| node_permissions
node_am -.->|"uses constants"| node_activityconstants
node_permissions -->|"looks up service"| node_servicemanager
node_permissions -->|"uses interface"| node_appops
node_reflection -->|"logs failures"| node_logger
node_reflection -->|"returns result"| node_methodresult
node_methodresult -->|"extends result"| node_invoke

click node_am "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/Am.java"
click node_base "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/BaseCommand.java"
click node_shellcmd "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/ShellCommand.java"
click node_intentcmd "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/IntentCmd.java"
click node_iam "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/IActivityManager.java"
click node_activityconstants "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/ActivityManager.java"
click node_receiver "https://github.com/termux/termuxam/blob/master/app/src/main/java/android/content/IIntentReceiver.java"
click node_crossversion "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/CrossVersionReflectedMethod.java"
click node_fakecontext "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/FakeContext.java"
click node_workarounds "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/Workarounds.java"
click node_permissions "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/PermissionUtils.java"
click node_reflection "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/ReflectionUtils.java"
click node_invoke "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/result/InvokeResult.java"
click node_methodresult "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/result/MethodInvokeResult.java"
click node_logger "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/logger/Logger.java"
click node_servicemanager "https://github.com/termux/termuxam/blob/master/app/src/main/java/android/os/ServiceManager.java"
click node_appops "https://github.com/termux/termuxam/blob/master/app/src/main/java/com/android/internal/app/IAppOpsService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_am,node_base,node_shellcmd,node_intentcmd,node_shell toneBlue
class node_iam,node_activityconstants,node_receiver toneAmber
class node_crossversion,node_fakecontext,node_workarounds,node_permissions,node_servicemanager,node_appops toneMint
class node_reflection,node_invoke,node_methodresult,node_logger toneRose
class node_platformam toneIndigo
```

## Components

### Command interface

- [AM command](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/Am.java): `app/src/main/java/com/termux/termuxam/Am.java`
- [Base command](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/BaseCommand.java): `app/src/main/java/com/termux/termuxam/BaseCommand.java`
- [Argument reader](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/ShellCommand.java): `app/src/main/java/com/termux/termuxam/ShellCommand.java`
- [Intent arguments](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/IntentCmd.java): `app/src/main/java/com/termux/termuxam/IntentCmd.java`

### Activity operations

- [Activity operations](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/IActivityManager.java): `app/src/main/java/com/termux/termuxam/IActivityManager.java`
- [Activity constants](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/ActivityManager.java): `app/src/main/java/com/termux/termuxam/ActivityManager.java`
- [Broadcast receiver stub](https://github.com/termux/termuxam/blob/master/app/src/main/java/android/content/IIntentReceiver.java): `app/src/main/java/android/content/IIntentReceiver.java`

### Android compatibility

- [Method adaptation](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/CrossVersionReflectedMethod.java): `app/src/main/java/com/termux/termuxam/CrossVersionReflectedMethod.java`
- [Caller context](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/FakeContext.java): `app/src/main/java/com/termux/termuxam/FakeContext.java`
- [Platform workarounds](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/Workarounds.java): `app/src/main/java/com/termux/termuxam/Workarounds.java`
- [Permission checks](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/PermissionUtils.java): `app/src/main/java/com/termux/termuxam/PermissionUtils.java`
- [Service lookup stub](https://github.com/termux/termuxam/blob/master/app/src/main/java/android/os/ServiceManager.java): `app/src/main/java/android/os/ServiceManager.java`
- [App-ops interface stub](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/android/internal/app/IAppOpsService.java): `app/src/main/java/com/android/internal/app/IAppOpsService.java`

### Runtime support

- [Reflection utilities](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/ReflectionUtils.java): `app/src/main/java/com/termux/termuxam/reflection/ReflectionUtils.java`
- [Invocation results](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/result/InvokeResult.java): `app/src/main/java/com/termux/termuxam/reflection/result/InvokeResult.java`
- [Method results](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/reflection/result/MethodInvokeResult.java): `app/src/main/java/com/termux/termuxam/reflection/result/MethodInvokeResult.java`
- [Logger](https://github.com/termux/termuxam/blob/master/app/src/main/java/com/termux/termuxam/logger/Logger.java): `app/src/main/java/com/termux/termuxam/logger/Logger.java`

### Other components

- **Shell user**
- **Android ActivityManager**

## Connections

- Shell user → AM command: invokes (evidence: `README.md`)
- AM command → Base command: uses (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- Base command → Argument reader: uses (evidence: `app/src/main/java/com/termux/termuxam/BaseCommand.java`)
- AM command → Argument reader: reads arguments (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- AM command → Intent arguments: parses intents (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- Intent arguments → Argument reader: reads arguments (evidence: `app/src/main/java/com/termux/termuxam/IntentCmd.java`)
- AM command → Activity operations: dispatches operations (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- Activity operations → Android ActivityManager: reflectively invokes (evidence: `app/src/main/java/com/termux/termuxam/IActivityManager.java`)
- Activity operations → Method adaptation: adapts methods (evidence: `app/src/main/java/com/termux/termuxam/IActivityManager.java`)
- Activity operations → Caller context: uses context (evidence: `app/src/main/java/com/termux/termuxam/IActivityManager.java`)
- Activity operations → Platform workarounds: applies workarounds (evidence: `app/src/main/java/com/termux/termuxam/IActivityManager.java`)
- Activity operations → Broadcast receiver stub: uses receiver (evidence: `app/src/main/java/com/termux/termuxam/IActivityManager.java`)
- AM command → Permission checks: checks permissions (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- AM command → Activity constants: uses constants (evidence: `app/src/main/java/com/termux/termuxam/Am.java`)
- Permission checks → Service lookup stub: looks up service (evidence: `app/src/main/java/com/termux/termuxam/PermissionUtils.java`)
- Permission checks → App-ops interface stub: uses interface (evidence: `app/src/main/java/com/termux/termuxam/PermissionUtils.java`)
- Reflection utilities → Logger: logs failures (evidence: `app/src/main/java/com/termux/termuxam/reflection/ReflectionUtils.java`)
- Reflection utilities → Method results: returns result (evidence: `app/src/main/java/com/termux/termuxam/reflection/ReflectionUtils.java`)
- Method results → Invocation results: extends result (evidence: `app/src/main/java/com/termux/termuxam/reflection/result/MethodInvokeResult.java`)
